-
-
Notifications
You must be signed in to change notification settings - Fork 12
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
base: main
Are you sure you want to change the base?
Conversation
MDLC01
left a comment
There was a problem hiding this 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.
Co-authored-by: Malo <[email protected]>
Co-authored-by: Malo <[email protected]>
|
Another question that should be resolved: Should Or, going further, perhaps the whole distinction should be removed entirely? (Tho I personally like it.) |
|
Changing the title to reflect the broader scope. |
Co-authored-by: Malo <[email protected]>
|
Also, I forgot to say this earlier: Thanks for the thorough review! |
MDLC01
left a comment
There was a problem hiding this 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.
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. |
|
I think it would be helpful to have them organized alphabetically, at least within a category. |
Co-authored-by: Malo <[email protected]>
I've now decided on "yes". |
I kept some groups in the generic section that are still sort of ordered by importance, but the others are now sorted alphabetically. |
Co-authored-by: Malo <[email protected]>
|
I'm wrong |
| 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. | ||
|
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| ## 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).
There was a problem hiding this comment.
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] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| - 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).
There was a problem hiding this comment.
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".
There was a problem hiding this comment.
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?
| - 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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| - 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, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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, |
As mentioned in #110 (comment).
These conventions are clearly contributing guidelines, so I went with
CONTRIBUTING.mdfor 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.rover.trfor corners (cf. #100).