-
-
Notifications
You must be signed in to change notification settings - Fork 11
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.
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
T0mstone
wants to merge
13
commits into
typst:main
Choose a base branch
from
T0mstone:conventions
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
bcd5486
Add conventions document
T0mstone 8cb3299
Implement suggestions
T0mstone baf9042
Implement suggestions (Part 2)
T0mstone 4f204e9
Fix and improve formatting
T0mstone 677e67f
Change formatting again
T0mstone b6fc5d6
Add last missing example
T0mstone 67550cf
Reformat slightly and add intro paragraph
T0mstone ceafd2e
Add paragraph for newcomers
T0mstone 4262c65
Add note about symbol name length
T0mstone 10d2545
Add note about diagonals
T0mstone 1d6e351
Re-order modifiers
T0mstone 49d8d1b
Fix Typst capitalization
T0mstone d23d15d
Fix typo
T0mstone File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,70 @@ | ||
# Contributing Guidelines | ||
Contributions are welcome! This document provides some resources and guidelines to help with the process. | ||
|
||
Symbol definitions are in `src/modules/`; The syntax should be mostly self-evident. | ||
If you need help with a contribution, you can ask us [on Discord](https://discord.com/channels/1054443721975922748/1277628305142452306). | ||
|
||
## Proposals | ||
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. | ||
|
||
## Conventions | ||
When adding new modules, symbols or variants, please try to be consistent with | ||
existing ones. Below are some guidelines based on existing symbols. These aren't | ||
always hard rules, especially because of how messy Unicode can be, but you should | ||
adhere to them if possible. | ||
|
||
### General Conventions | ||
- 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] | ||
This can have the following meanings: | ||
- 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`. | ||
- Notable exceptions to the previous convention: | ||
- When `.eq` is used in the second sense (stacked below), it only adds a single line and not two, | ||
e.g. `lt.eq`. For two lines below, `.equiv` is used, e.g. `lt.equiv`. | ||
|
||
[^modifname]: Though a modifier can also just coincidentally be a symbol name, e.g. `.not`. | ||
|
||
### Established Generic Modifiers | ||
These have a broad meaning and can have varying interpretations. | ||
<!-- Geometry --> | ||
- `.l`/`.r`/`.t`/`.b`: The four main directions (left/right/top/bottom), e.g. `arrow.l`, `times.r`. | ||
- For delimiters, `.l` means opening and `.r` means closing, e.g. `paren.l`, `quote.r`. | ||
- `.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, | ||
similarly to how `arrow.l.r` is an arrow pointing both left and right. | ||
- `.cw`/`.ccw`: Clockwise/Counterclockwise, e.g. `arrow.cw`, `integral.ccw`. | ||
- `.tiny`/`.small`/`.medium`/`.big`: A geometric shape with a certain size, e.g. `square.stroked.small`. | ||
<!-- Strokes --> | ||
- `.stroked`/`.filled`: A symbol that has an empty/filled interior, e.g. `circle.stroked`, `arrow.r.filled`. | ||
(They correspond to Unicode's "white"/"black".) | ||
- `.dotted`: A shape with a dotted line instead of a full stroke, e.g. `circle.dotted`. | ||
- `.light`/`.heavy`: A shape with a certain stroke weight, e.g. `checkmark.heavy`. | ||
<!-- Other (in alphabetic order) --> | ||
- `.alt`: An alternate glyph for the symbol, e.g. `phi.alt`. | ||
- `.double`, `.triple`, `.quad`: A symbol that has 2-4 of something, e.g. `excl.double`, `eq.quad`. | ||
|
||
### Established Concrete Modifiers | ||
These have a specific meaning that is not open to much interpretation. | ||
<!-- (in alphabetic order) --> | ||
- `.big`: A [large](https://www.unicode.org/Public/math/latest/MathClassEx-15.html) (n-ary) version | ||
of an operator, e.g. `union.big`. | ||
- `.inv`: Either vertically mirrored or a 180° rotated version of a symbol, e.g. `amp.inv`, `Omega.inv`. | ||
- See also [#108](https://github.com/typst/codex/issues/108). | ||
- `.not`: A negation of the symbol, e.g. `eq.not`. | ||
- `.o`: A symbol with a circle around it, e.g. `plus.circle`. | ||
- See also [#62](https://github.com/typst/codex/pull/62) | ||
- `.rev`: A horizontally mirrored version of a symbol, e.g. `in.rev`. | ||
- See also [#108](https://github.com/typst/codex/issues/108). | ||
- `.sq`: A "squarified" version of a symbol, e.g. `subset.sq`. | ||
- See also [#110](https://github.com/typst/codex/pull/110) |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.