|
| 1 | +# Contributing Guidelines |
| 2 | +Contributions are welcome! This document provides some resources and guidelines to help with the process. |
| 3 | + |
| 4 | +Codex collects related Unicode symbols as different *variants* of the same *symbol*.[^symbol] |
| 5 | +For example, `→ ⇒ ↑ ⇑` are four variants of the `arrow` symbol. |
| 6 | +Each symbol has a default variant (here `→`). |
| 7 | +To refer to a particular variant, *modifiers* can be appended to the symbol name |
| 8 | +using dot separators. |
| 9 | +For example `⇒` is `arrow.r.double`, `↑` is `arrow.t` and `⇑` is `arrow.t.double`. |
| 10 | +Modifiers are order-independent, so the latter can also be referred to as `arrow.double.t`. |
| 11 | +Additionally, not all modifiers have to be specified, in which case the best match[^match] |
| 12 | +will be taken. For example, `⇒` can also be referred to as `arrow.double`. |
| 13 | +Groups of related symbols are collected into *modules*. Modules can also contain other modules. |
| 14 | +Codex exports two top-level modules: `sym` for text-style symbols and `emoji` for emoji; |
| 15 | +Their source code is found in `src/modules/`. |
| 16 | + |
| 17 | +If you need help with a contribution, you can also ask us [on Discord](https://discord.com/channels/1054443721975922748/1277628305142452306). |
| 18 | + |
| 19 | +Proposals used to be written in a dedicated Proposals document, |
| 20 | +but new proposals should now be filed as GitHub issues instead. |
| 21 | +The [document](https://typst.app/project/riXtMSim5zLCo7DWngIFbT) |
| 22 | +has been repurposed to serve as a collection of useful information |
| 23 | +and naming ideas. |
| 24 | + |
| 25 | +[^symbol]: This document also uses "symbol" in the more abstract sense of a graphical symbol. |
| 26 | +[^match]: See the documentation of `ModifierSet::best_match_in` for the exact details. |
| 27 | + |
| 28 | +## Pull Requests |
| 29 | +- All PRs require two approvals by collaborators to be merged. |
| 30 | +- PRs with breaking changes require three such approvals instead. |
| 31 | +- PRs with changes to the public Rust API also require an approval by @laurmaedje. |
| 32 | + |
| 33 | +To remove a symbol or variant, it is first marked as deprecated |
| 34 | +(This is considered a breaking change). |
| 35 | +After a Typst version that includes this deprecation notice has been released, |
| 36 | +the deprecated symbol or variant will be removed (This is not considered a breaking change). |
| 37 | +Instead of being removed, the name can also be repurposed for a different symbol, |
| 38 | +which can be seen as a combination of removing the old symbol or variant |
| 39 | +and adding a new one with the same name. |
| 40 | + |
| 41 | +## Conventions |
| 42 | +When adding new modules, symbols or variants, please try to be consistent with |
| 43 | +existing ones. Below are some guidelines based on existing symbols. These aren't |
| 44 | +always hard rules, especially because of how messy Unicode can be, but you should |
| 45 | +adhere to them if possible. |
| 46 | + |
| 47 | +### General Conventions |
| 48 | +- English words use US spelling. |
| 49 | +- Modifier and module names are entirely lowercase. |
| 50 | +- Symbol names are lowercase unless the symbol is an uppercase letter. |
| 51 | +- Symbol names should be at least two characters long so they can be used easily in Typst's math mode. |
| 52 | +- When a symbol is added to a base, the symbol name is used as a modifier on the base.[^modifname] |
| 53 | + This can have the following meanings: |
| 54 | + 1. The symbol is added around or inside the base as a subordinate (smaller than the base), |
| 55 | + e.g. `eq.quest`, `triangle.stroked.dot`. |
| 56 | + 2. The symbol is stacked below the base, e.g. `gt.lt`. |
| 57 | + 3. The symbol is stacked to the right of the base, e.g. `colon.eq`. |
| 58 | + 4. The symbol is overlaid at the center of the base, e.g. `integral.dash`. |
| 59 | + 5. The symbol surrounds the base, e.g. `plus.square`. |
| 60 | +- Notable exceptions to the previous convention: |
| 61 | + - When `.eq` is used in the second sense (stacked below), it only adds a single line and not two, |
| 62 | + e.g. `lt.eq`. For two lines below, `.equiv` is used, e.g. `lt.equiv`. |
| 63 | + |
| 64 | +[^modifname]: Though a modifier can also just coincidentally be a symbol name, e.g. `.not`. |
| 65 | + |
| 66 | +### Established Generic Modifiers |
| 67 | +These have a broad meaning and can have varying interpretations. |
| 68 | +<!-- Geometry --> |
| 69 | +- `.l`/`.r`/`.t`/`.b`: The four main directions (left/right/top/bottom), e.g. `arrow.l`, `times.r`. |
| 70 | + - For delimiters, `.l` means opening and `.r` means closing, e.g. `paren.l`, `quote.r`. |
| 71 | +- `.tl`/`.tr`/`.bl`/`.br`: The four corners, e.g. `arrow.tl`, `triangle.stroked.tr`. |
| 72 | + - Generally, these are used for a single, diagonal direction, |
| 73 | + whereas combinations of two main directions (like `.t.l`) are used to mean both of them at once, |
| 74 | + e.g. `arrow.t.l`, if it existed, would be a bidirectional arrow that points both top and left, |
| 75 | + similarly to how `arrow.l.r` is an arrow pointing both left and right. |
| 76 | +- `.cw`/`.ccw`: Clockwise/Counterclockwise, e.g. `arrow.cw`, `integral.ccw`. |
| 77 | +- `.tiny`/`.small`/`.medium`/`.big`: A geometric shape with a certain size, e.g. `square.stroked.small`. |
| 78 | +<!-- Strokes --> |
| 79 | +- `.stroked`/`.filled`: A symbol that has an empty/filled interior, e.g. `circle.stroked`, `arrow.r.filled`. |
| 80 | + (They correspond to Unicode's "white"/"black".) |
| 81 | +- `.dotted`: A shape with a dotted line instead of a full stroke, e.g. `circle.dotted`. |
| 82 | +- `.light`/`.heavy`: A shape with a certain stroke weight, e.g. `checkmark.heavy`. |
| 83 | +<!-- Other (in alphabetic order) --> |
| 84 | +- `.alt`: An alternate glyph for the symbol, e.g. `phi.alt`. |
| 85 | +- `.double`, `.triple`, `.quad`: A symbol that has 2-4 of something, e.g. `excl.double`, `eq.quad`. |
| 86 | + |
| 87 | +### Established Concrete Modifiers |
| 88 | +These have a specific meaning that is not open to much interpretation. |
| 89 | +<!-- (in alphabetic order) --> |
| 90 | +- `.big`: A [large](https://www.unicode.org/Public/math/latest/MathClassEx-15.html) (n-ary) version |
| 91 | + of an operator, e.g. `union.big`. |
| 92 | +- `.inv`: Either vertically mirrored or a 180° rotated version of a symbol, e.g. `amp.inv`, `Omega.inv`. |
| 93 | + - See also [#108](https://github.com/typst/codex/issues/108). |
| 94 | +- `.not`: A negation of the symbol, e.g. `eq.not`. |
| 95 | +- `.o`: A symbol with a circle around it, e.g. `plus.o`. |
| 96 | + - See also [#62](https://github.com/typst/codex/pull/62) |
| 97 | +- `.rev`: A horizontally mirrored version of a symbol, e.g. `in.rev`. |
| 98 | + - See also [#108](https://github.com/typst/codex/issues/108). |
| 99 | +- `.sq`: A "squarified" version of a symbol, e.g. `subset.sq`. |
| 100 | + - See also [#110](https://github.com/typst/codex/pull/110) |
0 commit comments