Skip to content

Add contributing guidelines #112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 13 commits into
base: main
Choose a base branch
from
Open

Add contributing guidelines #112

Changes from 1 commit
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
bcd5486
Add conventions document
T0mstone Jul 15, 2025
8cb3299
Implement suggestions
T0mstone Jul 16, 2025
baf9042
Implement suggestions (Part 2)
T0mstone Jul 16, 2025
4f204e9
Fix and improve formatting
T0mstone Jul 16, 2025
677e67f
Change formatting again
T0mstone Jul 16, 2025
b6fc5d6
Add last missing example
T0mstone Jul 16, 2025
67550cf
Reformat slightly and add intro paragraph
T0mstone Jul 16, 2025
ceafd2e
Add paragraph for newcomers
T0mstone Jul 16, 2025
4262c65
Add note about symbol name length
T0mstone Jul 16, 2025
10d2545
Add note about diagonals
T0mstone Jul 21, 2025
1d6e351
Re-order modifiers
T0mstone Jul 21, 2025
49d8d1b
Fix Typst capitalization
T0mstone Jul 21, 2025
d23d15d
Fix typo
T0mstone Jul 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Conventions
When adding new modules, symbols or variants, please try to be consistent with
the following list of conventions. These aren't always hard rules, especially
because of how messy Unicode can be, but you should adhere to them if possible.

General conventions:
- Modifiers are entirely lowercase.
- Modifiers that correspond to symbols (by having the same name) have six established meanings:
- The symbol is added around the base like an accent or an attachment (smaller than the base), e.g. `eq.quest`.
- 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`.
- The symbol is placed inside the base, e.g. `triangle.stroked.dot`.
Established generic modifiers:
- `.l`/`.r`/`.t`/`.b`: The four main directions (left/right/top/bottom).
- For delimiters, `.l` means opening and `.r` means closing (see [#100](https://github.com/typst/codex/pull/100)).
- `.tl`/`.tr`/`.bl`/`.br`: The four corners
<!-- TODO: Do we have or want to have conventions about when to choose `.tl` vs. `.t.l`? -->
Copy link
Collaborator

Choose a reason for hiding this comment

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

.tl designates the top-left corner, whereas .t.l (which AFAIK doesn't really exists at the moment appart from bracket.{l,r}.tick.{t,b}) is a combination of both .t and .l. For example, arrow.t.r would be an arrow pointing both top and to the right, similarly to how arrow.l.r is an arrow pointing both left and right.

The case of corner delimiters is special because we want to signal opening and closing delimiters, as explained in #100.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Fair enough. Should I add a clarification for this or do you think it just goes without saying?

Copy link
Collaborator

Choose a reason for hiding this comment

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

If you mean a clarification regarding corner delimiters, I don't think this is necessary.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

No I mean basically a reworded version of your first paragraph from before:

.tl designates the top-left corner, whereas .t.l [...] is a combination of both .t and .l. For example, arrow.t.r would be an arrow pointing both top and to the right, similarly to how arrow.l.r is an arrow pointing both left and right.

Copy link
Collaborator

Choose a reason for hiding this comment

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

It's a bit weird to talk about a symbol that doesn't exist, but I think this is a good way to explain things so let's add that

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Is 10d2545 good?

- `.double`, `.triple`, `.quad`: A symbol that has 2-4 of something.
- `.stroked`/`.filled`: A symbol that has an empty/filled interior.
(They correspond to Unicode's "white"/"black".)
- `.tiny`/`.small`/`.medium`/`.big`: A geometric shape with a certain size.
- `.light`/`.heavy`: A shape with a certain stroke weight.
- `.dotted`: A shape with a dotted line instead of a full stroke.
Established concrete modifiers:
- `.big`: A big (n-ary) version of an operator.
- `.alt`: An alternative version that is still more or less the same symbol.
- `.not`: A symbol with a (typically diagonal) line through it.
- `.o`: A symbol with a circle around it (see [#62](https://github.com/typst/codex/pull/62))
- `.sq`: A "squarified" version of a symbol (see [#110](https://github.com/typst/codex/pull/110))
- `.rev`: A horizontally mirrored version of a symbol (see [#108](https://github.com/typst/codex/issues/108))
- `.inv`: Either vertically mirrored or a 180° rotated version of a symbol (see [#108](https://github.com/typst/codex/issues/108))
- `.cw`/`.ccw`: Clockwise/Counterclockwise
Established exceptions:
- When `.eq` is used in the second sense (stacked below), it only adds a single line and not two.
For two lines below, `.equiv` is used.
- `.not` (see above) does not correspond to the symbol `not` despite having the same name.