diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6f97551 --- /dev/null +++ b/CONTRIBUTING.md @@ -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. + +- `.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`. + +- `.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`. + +- `.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. + +- `.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)