Skip to content

Conversation

@T0mstone
Copy link
Collaborator

As mentioned in #110 (comment).

These conventions are clearly contributing guidelines, so I went with CONTRIBUTING.md for the file name. That way we can also add other contributing guidelines in the future, if we want to.

If you want to reword something or add other conventions that I may have missed, don't hesitate to leave a comment.

From my side, there's only one unresolved question left here (which I also left as a TODO comment in the file itself), namely whether we want to write something about when we choose e.g. .t.r over .tr for corners (cf. #100).

@T0mstone T0mstone added enhancement New feature or request meta Discussion about the structure of this repo labels Jul 15, 2025
Copy link
Collaborator

@MDLC01 MDLC01 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My personal view is that this document should be used as a way to quickly find precedents, but that new names should always be motivated by existing symbols. In other words, those guidelines should reflect the existing conventions and shouldn't be used as a source of truth--the only source of truth is the existing names. For this reason, I strongly believe every rule in this document should be supported by one or multiple examples. This is reflected in my proposed rephrasing of the first paragraph.

Unrelatedly, if this document aims to be contributor guidelines, it might benefit from some of the links from the "Useful links" section of the proposals document. Maybe even a link to the document itself.

@T0mstone
Copy link
Collaborator Author

Another question that should be resolved: Should .cw and .ccw be generic modifiers instead?

Or, going further, perhaps the whole distinction should be removed entirely? (Tho I personally like it.)

@T0mstone T0mstone changed the title Add conventions document Add contributing guidelines Jul 16, 2025
@T0mstone
Copy link
Collaborator Author

Changing the title to reflect the broader scope.

@T0mstone
Copy link
Collaborator Author

Also, I forgot to say this earlier: Thanks for the thorough review!

Copy link
Collaborator

@MDLC01 MDLC01 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or, going further, perhaps the whole distinction should be removed entirely?

Maybe just ordering the modifiers from most concrete to least concrete would be enough. I personally don't see a clear cut distinction.

@T0mstone
Copy link
Collaborator Author

Maybe just ordering the modifiers from most concrete to least concrete would be enough. I personally don't see a clear cut distinction.

Hmmm, I'd like to hear the other maintainers' opinions on this. Tho I'd definitely want to order them from least to most concrete instead.

@Enivex
Copy link
Collaborator

Enivex commented Jul 18, 2025

I think it would be helpful to have them organized alphabetically, at least within a category.

@T0mstone
Copy link
Collaborator Author

T0mstone commented Jul 21, 2025

Another question that should be resolved: Should .cw and .ccw be generic modifiers instead?

I've now decided on "yes".

@T0mstone
Copy link
Collaborator Author

I think it would be helpful to have them organized alphabetically, at least within a category.

I kept some groups in the generic section that are still sort of ordered by importance, but the others are now sorted alphabetically.

@Enivex
Copy link
Collaborator

Enivex commented Jul 23, 2025

I think typst should be typeset in lowercase?

I'm wrong

@T0mstone T0mstone added the waiting on reviews Breaking and non-breaking changes need respectively 3 and 2 reviews label Oct 8, 2025
Proposals used to be written in the [Proposals document](https://typst.app/project/riXtMSim5zLCo7DWngIFbT),
although it is now preferred to have a GitHub issue for each one.
Nonetheless, the document still contains a lot of useful information.

Copy link
Collaborator

@knuesel knuesel Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Terminology
In this project, related Unicode characters are grouped as *variants* under a common *symbol*.
For example, `→ ⇒ ↑ ⇑` are four variants of the `arrow` symbol. Each symbol has a default variant
(here ``). To refer to a particular variant, *modifiers* can be appended to the symbol name
using dot separators. For example `` is `arrow.double`, `` is `arrow.t` and `` is
`arrow.double.t`. The order of modifiers is generally not important so the latter can also be
referred to as `arrow.t.double`.
Large categories of symbols are further grouped into *modules*, There are currently two modules:
`sym` for regular symbols and `emoji` for emojis.
This document also uses "symbol" in the more abstract sense of a graphical symbol.

I think the document could use some clarification of the terminology (though eventually this should
be moved to a proper documentation page).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A bit of this is already in the lib.rs doc-comment, but I suppose it doesn't hurt repeating it here.

- Modifier and module names are entirely lowercase.
- Symbol names are lowercase unless the symbol is an uppercase letter.
- Symbol names should be at least two characters long so they can be used easily in Typst's math mode.
- When a symbol is added to a base, the symbol name is used as a modifier on the base.[^modifname]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- When a symbol is added to a base, the symbol name is used as a modifier on the base.[^modifname]
- For variants that add a geometric shape to a base symbol, the shape name is used as modifier with one of the following meanings:[^modifname]

I think this clarifies it a bit (I was initially confused by the double meaning of "symbol" and no mention of variant).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I slightly disagree. This is specifically about when we already have an existing symbol for the added shape. That's what I meant by "When a symbol is added to a base".

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. But don't we want to apply the same rules regardless of whether the shape is already its own symbol? For example I think we would want plus.square to follow these rules, even if we didn't have a square symbol on its own?

Comment on lines +25 to +30
- The symbol is added around or inside the base as a subordinate (smaller than the base),
e.g. `eq.quest`, `triangle.stroked.dot`.
- The symbol is stacked below the base, e.g. `gt.lt`.
- The symbol is stacked to the right of the base, e.g. `colon.eq`.
- The symbol is overlaid at the center of the base, e.g. `integral.dash`.
- The symbol surrounds the base, e.g. `plus.square`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- The symbol is added around or inside the base as a subordinate (smaller than the base),
e.g. `eq.quest`, `triangle.stroked.dot`.
- The symbol is stacked below the base, e.g. `gt.lt`.
- The symbol is stacked to the right of the base, e.g. `colon.eq`.
- The symbol is overlaid at the center of the base, e.g. `integral.dash`.
- The symbol surrounds the base, e.g. `plus.square`.
1. The shape is added around or inside the base as a subordinate (smaller than the base),
e.g. `eq.quest`, `triangle.stroked.dot`.
2. The shape is stacked below the base, e.g. `gt.lt`.
3. The shape is stacked to the right of the base, e.g. `colon.eq`.
4. The shape is overlaid at the center of the base, e.g. `integral.dash`.
5. The shape surrounds the base, e.g. `plus.square`.

Goes together with the previous suggestion. Also since we refer below to the "number 2" we might as well number the list.

- `.tl`/`.tr`/`.bl`/`.br`: The four corners, e.g. `arrow.tl`, `triangle.stroked.tr`.
- Generally, these are used for a single, diagonal direction,
whereas combinations of two main directions (like `.t.l`) are used to mean both of them at once,
e.g. `arrow.t.l`, if it existed, would be an arrow that points both top and left,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
e.g. `arrow.t.l`, if it existed, would be an arrow that points both top and left,
e.g. `arrow.t.l`, if it existed, would be a two-headed arrow that points both top and left,

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request meta Discussion about the structure of this repo waiting on reviews Breaking and non-breaking changes need respectively 3 and 2 reviews

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants