RFC Ideas

[tingerrr]

Here's a list of things that people have thought about standardizing in some form or fashion:

• Standard Template Entrypoint API
  A standardized API for templates could make it easier for people to easily use multiple templates (as it happens with presentations and, posters and theses all requiring similar inputs).
  Initial research is done by @PgBiel with elembic as a possible stepping stone towards APIs with custom types in Typst proper.
  • Template-Independent Author Information Schema
    This was suggested by @jamesrswift and partially implemented in valkyrie, but it currently lacks widespread adoption. Standardization could be especially helpful for authors who create presentations alongside their documents, or who intend to write different versions of one document. This has some overlap with the standard API guidelines below.
• Doc Comment Syntax
  A widely used syntax in the community is available with tidy's v0.3.0 comment syntax, this version is supported by tinymist, which helped its adoption. A second version of this was extensively discussed in Add api and style section about documentation package-api-guidelines#8. While it was implemented in tidy v0.4.0, it was not further pursued by the tinymist authors. @Myriad-Dreamin has offered to author a document on the standardization of the doc syntax to reiterate his points in this decision. ¹
• Default Project Structure
  The standardization of a project structure for both complex (multi-file) documents and packages/templates would help reduce the burden on maintainers and authors to configure various tools. Some initial research on what would constitute a good standard structure were done by @SillyFreak and @jamesrswift in https://github.com/typst-community/typst-package-template. The work done on this repo could eventually be turned into a standard supported by many 3rd-party Typst tools.
• Conventional API Guidelines
  Some initial design work was done in https://github.com/typst-community/guidelines, but it has since stalled. A collection of standard API design practices help strengthen the principle of least surprise and makes switching or combining packages easier.
• Conventional Style Guidelines
  Similar to the API guidelines, initial work was done but has since stalled. Typstyle may serve as a good piece of research on what should be a preferred standard style. A standardized style across the ecosystem makes it easier for contributors and maintainers to read and maintain code across many packages.
• Test Syntax & Structure
  Standardization of test syntax and structure would help package/template authors in particular to reduce the split in tooling that currently exists between tytanic and tinymist and make it easier for new testing solutions to be backwards compatible with packages. This is something I'm particularly interested in, though, it will be some time until work on this can begin from tytanic's side, so I wouldn't see this as particularly urgent.
• Package Manager Features
  The various package manager implementations that currently exist could benefit from all supporting the same common features.

The primary motivation for standardization is to reduce friction for both existing maintainers and new Typst community members.

This tracking issue can serve as a place of open discussion to get certain RFCs started, feel free to suggest other topics. Make sure to check out the community forge on the Typst discord to discuss your ideas in real time.

Footnotes

1. The suggestion to author a document detailing the benefits and drawbacks of the different doc comment versions actually kicked off the creation of this repository. ↩

[Thumuss]

As I was saying on the Community thread, we could potentially research an optimise registry for typst.
The GitHub repository packages is good enough for now but at long term it would become a problem, such as organizations namespaces, automatic deployment (which for now doesn't exist completely), evaluate ancient version compatibility (could be produced by a test env created by the user publishing the package or tytanic), etc.
Something important too with that in mind is a proper package management to work with local and organizations level (it's a bit developed on the utpm package but it's just an overview of what we can achieve and it's not part of the typst CLI itself).

[tingerrr]

As noted on the community forge, a registry is not something we have much control over, this is something that is already planned by Typst itself anyway.

I've added the package manager features as an entry.

[PgBiel]

I feel we have a good opportunity now to attempt to "standardize" (or at least give a recommendation for) template configuration using custom elements thanks to elembic. We have some preliminary discussion ongoing here: PgBiel/elembic#69 (comment)

[tingerrr]

This is definitely a superset of the first topic, we could add this as its own entry, but I have some concerns.

Right now there is one package adding support for a feature that will eventually be added to Typst. I find it unlikely that someone else will create a new package, but of course this is possible.

As long as there is only one package, standardizing how to use that package seems like an odd choice. In my mind, that would only slow down the process of changing those recommendations of use. I think leaving the recommendations or guidelines on the usage of elembic within elembic makes more sense. If however we consider only the top level API templates should have regardless of elembic/built-in types, then I'm all for an RFC. I assume you meant the latter, but I'm jsut asking to make sure.

[PgBiel]

Yes, you make an important point. I believe we can make something that doesn't depend on elembic, but use elembic as a way to test and develop those ideas. Fully agree that elembic should keep its own recommendations to itself.

[PgBiel]

I should also clarify that I think the ongoing discussion on elembic will be an important first step for a more general discussion in the future, and so I invite the community to give their opinions, however that particular discussion shouldn't be the subject of a typst-community RFC.

[tingerrr]

I've expanded the first entry and added your PR as a point of initial research towards uniform template APIs.

[yodatak]

I would love to have some elements as packages, like I just want elements to make a like
a 2 colons list, a bold title, subtitles and many other some more elements to make book and not using a PAO software, composant to make socials icons and social contact , some contact footer , and be able to reuse theming with different composants ( would love to have some markup style like in libreoffice) and so on would love to have more somethink like the dioxus composants but to make tempates or some nice looking thing in text or some componants like this
gentle-clues
https://dioxuslabs.com/components

[tingerrr]

I think parts of this definitely fit into the first point, while others might just be package specifics.

[tingerrr]

For those interested, a doc syntax RFC PR is up on #6.