Unintuitive Names

[boreal plover]

I’m using this to comment on any syntax I find unintuitive, difficult to follow, or hard to discover, so it can be improved. (And I encourage others to leave their own comments in this thread!)

dot being a period instead of the dot product. If I wanted a period I would type a period. The lack of cdot (the LaTeX alternative) makes this even more confusing. The fact that this is hidden behind a method that I can only call with dot.op is completely inexplicable to me. To be fair, I have never been a fan of OOP. That being said this is a bridge too far; methods should be for getting the properties of an object, or for cases where an object is clearly the one “doing” something. I have no idea what the dot itself is “doing” (yeeting itself up half a line?)

alef saves one character over aleph but is a substantially less common spelling, especially in math.

nabla feels less intuitive than grad, but I can totally understand if that’s just a preference thing. (Anyone else have a preference for grad?)

In general I feel like a line break in a $$ block should equal a line break in the displayed equation, unless I specify otherwise; usually when I start a new line I’m doing that because I want to move to the next line of the equation. I frequently forget to add \.

It’s weird that vec(x) doesn’t do what I’m used to in LaTeX (add a vector arrow above x).

[sullen vine]

btw, it's dot.c iirc

although I admit I prefer cdot, but that's consistent with the Typst Way™️ at least

[median granite]

Counterpoints:

Linebreaks operating the same way in a paragraph and in math mode seems more consistent. But you could make the same argument that raw of course has a different behavior that math could be like instead.

Nabla / del is the proper name of the symbol. In some contexts (but not all!) it is used to represent the gradient operation.

Alef is named as such more likely because that is the unicode name, not shorthand.

[arctic solar]

i much prefer nabla

likewise I much prefer aleph

[pliant root]

Filed https://github.com/typst/typst/issues/724

[boreal plover]

* is important to keep the same, it’s commonly used for convolutions

[digital crown]

While convolutions are a common operations, multiplications are more so

[wind isle]

Most multiplication is implicit

[digital crown]

While that's true I think the mnemonic of * and / should be kept intact

[wind isle]

I disagree, because it's so rarely used. And * isn't just used for convolutions

It's also used as a superscript to denote duals for instance

[digital crown]

The dot product of matrices is a fairly common operation

Is that also shortened to be implicit?

[wind isle]

Do you mean dot product of vectors?

[digital crown]

Yes yes

I keep mixing those up

[wind isle]

No, that would not be implicit, though it's often written using transpose, or with inner product notation (x,y) or <x,y> (not the correct delimiters, but I can't be bothered to find the right ones on my phone)

I added my suggestion of making dot.c work like dot.op in math mode (matching latex' cdot)

[digital crown]

What does the c even mean then

Isn't the point of the default symbols to have more clear names

[wind isle]

Center

[digital crown]

Uh huh

Then it should be center, prefer to alias symbols if you want to type less

[wind isle]

You can always alias them yourself

[digital crown]

But the defaults should be clear

Because like you just said

You can always alias them yourself

[wind isle]

I think the idea is that it's dot.c because everyone using typst will be familiar with cdot from latex

[digital crown]

Yeah but it has been said before, we shouldn't talk from latex what was not good

[wind isle]

Though then it's confusing that it's not the same Unicode character currently....

[digital crown]

Latex is not a good standard for it's macro names

Rather for it's output

[wind isle]

I think dot.c is fairly descriptive. Though I could agree that dot is probably more readable. If you actually need a period you can simply write .

[digital crown]

I mean dot.center or op.dot.center

Simply not using abbreviations in this

Or at least

Not one letter abbreviations

This will go out of hands when new things are added

Can already see suggestions for .n as an alias for the not modifier

[wind isle]

I know what you meant, but it depends how often the symbol is used. Having short default names for very commonly used symbols is not a bad thing.

[zealous scarab]

Maybe this should be renamed to "Unintuitive symbol names"

I was surprised by the contents of thread

Regarding dot.op. Maybe @fierce jackal has something to say, this was actually changed during the preview phase.

There also the point that the symbol names aren't necessarily math specific and sym.dot makes much more sense as the normal period not the operator.

[wind isle]

For a normal period you already have . on your keyboard though

[digital crown]

In the end the names should be intuitive enough that even a non math person would find most of the symbols by using the web editors auto complete and a little bit of common sense

[wind isle]

That being said, symbol naming isn't exactly the most important thing. There are bigger fish to fry right now 🙂

[wind isle]

If you search for dot you would see all of them listed. It's not exactly a stretch to deduce that c means center(ed)

[digital crown]

I guess that's fair

But I stand by that the default should be explicit

I think that is just my personal preference

[fierce jackal]

I'm on the boat that:

• dot should be dot.op; it's just way more common. (And, as @wind isle said, if I wanted a normal period I would just use ., both in math mode and in text mode)
• If this change is made, then * should absolutely be kept as the operator for convolution

If we are for some reason not willing to change dot -> dot.op, then it sounds maybe fine to do * -> dot.op (but I'm not a big fan of it, because in math there are many kinds of "multiplication", not all of them written with a dot)

Also, the dot is used for a lot of stuff that isn't some form of multiplication.

[zealous scarab]

This is from when it was changed: #preview-members message

(Just a bit of history trivia)

[sullen vine]

I’m not sure but I think changing * to anything other than asterisk could get very confusing for the common user

[digital crown]

while I think asterisk as convolution makes sense, keep in mind that / means division here and the mnemonic will not hold up for * which is used as multiplication in regular text

think of someone who uses excel a lot or does a lot of financial work

[sullen vine]

Yeah , * could even (in a stretch) be a centralized dot or smth to indicate multiplication , but even then could still be confusing

So imho better to keep it as an asterisk

[digital crown]

I think for ease of typing it makes sense to have it as asterisk

it will just be confusing to some is what I'm saying

[sullen vine]

Yeah yeah

[digital crown]

and expected behavior to others

[sullen vine]

Regardless we always have our good ol’ “show”

And custom functions

[digital crown]

i don't think show works in math mode does it?

[sullen vine]

Uhhh… well, now that you mention it, I don’t remember how much of it works there

I think it’s quirky

Anyway, this should probably improve over time

[boreal plover]

It’s probably one of the more important things to get right early (because later on it can’t be changed)

But like, 90% of why Python or Julia code is cleaner than Java is because all the functions have clear names

[wind isle]

I mean, early is relative. Obviously you want to get it right before it's mature, but typst is still very much in flux.

[boreal plover]

Unintuitive Names

[viral shore]

I disagree with this. It might seem like a good idea for short equations but organising long equation code will become harder if you need to squish everything onto one line.

[boreal plover]

You don’t have to. You can just introduce a different syntax to mean “line break that doesn’t actually insert a line break”

One way to do this would be to switch the meaning of \ to be the opposite of what it is now. Alternatively, this could be done with indentation, or ending a line with // (as if commenting out the new line, which is how you do this in text mode)

Actually I think that last one sounds best. It makes math mode as consistent with text mode as possible

[viral shore]

Ok, this makes more sense and I like later one to make everything consistent. Didn't dig into source code so don't know if they use external engine to render math.

[boreal plover]

@zealous scarab do you think this would be a good way to do line breaks? A new line always introduces a line break (whether you’re in math mode or text mode), unless ended with // to comment out the line.

[fierce jackal]

Ending in comment would be a really messy way to denote this

Language design aside, on the compiler the way comments work is that they are stripped out at the lexer stage

so before you even have a preliminary AST

we can change that, but I see little point

On the language design side now, I don't see why a comment at the end of the line should be thought of as "commenting out the newline" rather than just being a trailing comment

and mind you, if we want consistency, we'd have to implement the same behaviour of "commenting out the newline" for text mode

Now, I'm a big fan of the idea of switching the meaning of \ in math (or some other mechanism). Just don't mess with comments.

Also not a big fan of using indetation for this, sounds like it would be rather finicky.

[wraith citrus]

Alef is named as such more likely because that is the unicode name, not shorthand.

[wraith citrus]

likewise I much prefer aleph

¿Por qué no los dos?

html entities allow ℵ and ℵ
https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references

[wind isle]

Please god no

[zealous scarab]

I do not like this. We specifically did not want the TeX hack where an empty trailing comment can carry meaning. I think a single backslash per line isn't that bad and it's explicit.

[boreal plover]

I think it’s reasonable if you don’t want an empty trailing comment to have meaning, but it currently does? If I end a paragraph in text mode with an empty comment, it smooshes together the neighboring paragraphs.

If you want something else, I think using \ to mark places where there is no line break is reasonable

But that might get confusing, so how about using indentation? e.g.

$
f(x) = 
2 y
$

Displays as two lines. But

$
f(x) = 
    2 y
$

Displays as 1, since the 2nd line is considered part of a “block” that falls under the first line.

[wind isle]

Significant whitespace is an abomination

[wind isle]

That sounds like a bug

[boreal plover]

I mean, you’re free to think that, but it’s already there in Typst (e.g. list behavior)

[wind isle]

In text mode, sure

[pliant root]

Not a bug since that's how < 2 line breaks in text mode works

Filed https://github.com/typst/typst/issues/786 for the \ in math mode

That's such a great idea as writing multiline equations is just as annoying as in latex which is a bummer, but this would fix it

[wind isle]

I don't see why writing \ is that annoying

[pliant root]

Cuz wanting a newline is the default for most of my equations

It super rare that I'll break up the text of an equation into multiple for code clarity since my equations aren't longer than ~150 chars

Maybe it's flipped for you and you're always writing extremely long equations?

[wind isle]

Often long enough that you want to break them up for readability, yes

[pliant root]

Hmmm, that's a bummer

Though actually hold on

?render

text
$
"testing" &= "foobar" \
"yo" &= "blah" \
$

text
$
\ "testing" &= "foobar"
\ "yo" &= "blah"
$

text
$
"testing" &= "foobar" \
&= "blah" \
$

text
$
\ "testing" &= "foobar"
\ &= "blah"
$

[pliant root]

I'm curious how you write your equations

I currently use the trailing slash style which is annoying because it means there are two places where I need to keep styling metadata around. And if I have &= ... & "By theorem foo" \ for example, I can't just duplicate the line and delete everything from the last & since I need the \.

So maybe a better style is to put the \ at the beginning of the line with the other prefix type stuff

To make that look consistent, we'd need to strip the first line break

[wind isle]

I use trailing slash indeed.

[pliant root]

K

I'm going to try prefix slash for a bit and if it seems good I'll propose we strip the first one

[boreal plover]

That’s reasonable, but I’m guessing it’s <50% of the time.

An idea; maybe this could be an option you could #set?

[digital crown]

#set should not be able to change the semantic meaning behind syntax, only it's rendering output

[wind isle]

Optional semantics is a can of worms

[patent swift]

Moving this to github

[swift depot]

I would argue that the dot.op syntax has nothing to do with OOP. Namespaces regularly use this syntax.

[marble seal]

people who don't like OOP have this burning desire to find some way to let you know

[digital crown]

I dind't even see oop mentioned before?

ok nvm

[marble seal]

honestly that statement alone makes any of their issues null and void. I say close them.

[digital crown]

a) moved to github
b) other concerns that were brought up were very much valid

[marble seal]

good

if it's on github don't see why we need to keep this thread open

[boreal plover]

They do, but the practice of placing methods in the namespace of their arguments is a mostly OOP thing. In a non-OOP language you'd be able to write this as center(dot). But if you want to call this "not OOP," that's fine too.

But in that case what I'm objecting to here is how it's extremely counterintuitive trying to predict what "namespace" a method belongs to, because many symbols fall inside another symbol's namespace, making it hard to find the symbol you want. I never would have guessed that \pm is plus.minus; it took me a while to figure that one out.

[boreal plover]

Like, if we do want to go down this path of reducing the number of symbols by introducing ways to compose symbols, can I propose:
stack(plus, minus)
stack(dot, plus)
And so on? I find this a lot more intuitive

I don't have a particular problem with the x.y syntax in general--I think exists.not is totally reasonable for example. But the way it's being used right now is unintuitive for sure

[wraith citrus]

I don't really care as long as the names are reasonable and there's a good catalog showing all the symbols, as well as highlighting the differences between latex and typst

[sullen vine]

Alright guys, can we please move this conversation to GitHub (e.g. create a discussion in https://github.com/typst/typst/discussions )? I'll be locking the thread later. Thanks buddies 👍