anr-aapg-fanmade:0.1.0

[gasche]

I am submitting

• a new package
• an update for a package

This package consistents in a style library for ANR AAPG grant proposals -- grant proposals of French National Research Agency (ANR), the main funding body for French research grants. It would of use to anyone interested in using Typst to write an ANR grant proposal, instead of the official .docx files provided or the unofficial LaTeX packages.

I have read and followed the submission guidelines and, in particular, I

• selected a name that isn't the most obvious or canonical name for what the package does
• added a typst.toml file with all required keys
• added a README.md with documentation for my package
• have chosen a license and added a LICENSE file or linked one in my README.md
• tested my package locally on my system and it worked
• excluded PDFs or README images, if any, but not the LICENSE

Notes

ANR submissions are in two phases (first submit a pre-proposal, then if approved write a full proposal).

The ANR funding agency provides .docx templates that contain the skeleton of a submission, including recommended layout, section titles, and also a bunch of recommendations on how to fill each section. The expected workflow for those .docx files is that grant authors fill out each section, and gradually remove the recommendations as they go along.

The typst package proposes the same workflow with two .typ files: first-proposal.typ and second-proposal.typ, which contain in particular the relevant ANR recommendations (they differ between the two phases).

It would be nice to expose first-proposal.typ and second-proposal.typ as typst Templates, instead of forcing users to find the README file, find the link, and copy them. This is not done for two reasons:

1. Typst does not support exposing several template files per package -- see Support multiple templates per package #1059 . The proposed workaround is to publish three packages, one for aapg.typ and then one for each template. This is too much hassle for me.
2. The files {first,second}-proposal.typ can cannot be released under an open-source license, because they contain the ANR recommendations verbatim. The Typst packaging requirements demand that a template file can be distribued under an open-source license by users "after being modified through normal use". One plausible interpretation of "normal use" could be that users will indeed manually remove all ANR recommendations from the output, and then the result could be published under the terms of their choice (... modulo the issue that the titles of each section are provided by the ANR as well).

[gasche]

I updated the package to take the warnings of the CI into account. Two warnings remain about named argument to the package configuration function that are acronyms in uppercase (AAPG and CES). The automated warnings worry that this may be an instance of CamelCase and recommend kebab-case instead. But I think that in this case keeping the acronyms capitalized makes things significantly more readable for package users, so I propose to keep the argument names that way.

[elegaanz]

For the CI warnings, this is definitely a false positive, don't worry about it.

For the template part, I think it could make sense to have a single template with both files (and the default entrypoint set to first-proposal.typ) as a workaround, it would provide a better experience than the current setup in my opinion. But this is ultimately up to you.

Regarding the license of these files, I will assume that you wanted to write "can't" here:

The files {first,second}-proposal.typ can be released under an open-source license, because they contain the ANR recommendations verbatim.

In that case, I don't think it will change anything to keep them out of the template, as packages distributed to Typst Universe must be under an open-source license. The part you are quoting is for the opposite situation: when a template is under an open-source license (as it should be) but the users may want to share their derivative works under an incompatible license.

If I'm mistaken and you actually wanted to write "can", I don't think there is any issue here, even if you were to put these two files in a template.

[gasche]

You are correct, I meant "cannot", I will edit to fix this.

The first-proposal.typ and second-proposal.typ are not under an open-source license -- they contain text that has been widely, publicly distributed by a funding agency with the purpose of being used in exactly this way, but with no clear copyright guidance as the intent is to have users remove the content before they publish their own documents.

The style code itself in aapg.typ is authored by me and ISC-licensed. This is what users need to import in their own documents -- whether they write it from scratch or work by progressively erasing the ANR-written guidelines. My understanding is that aapg.typ is what could be reasonably called "the package" when reading the typst packaging guidelines.

Each file comes with an explicit mention in the header of its licensing regime, in particular first-proposal.typ and second-proposal.typ have an explicit header mentioning that their content is not open source.

My understanding is that there are other packages that include assets that are not themselves under an open-source license, typically the logo of the institution for institution-specific templates (for example this logo, which is probably covered by the following rules restricting its usage to schorlarly purposes). I view including {first,second}-proposal.typ under this light: they bring a large part of the value of the package (you cannot produce a conformant thesis/report without including the logo, and it's hard to write a grant without reading the funder's recommendations), they are not the Typst code, and it is the end-users' responsibility to use them appropriately.

For the template part, I think it could make sense to have a single template with both files (and the default entrypoint set to first-proposal.typ) as a workaround, it would provide a better experience than the current setup in my opinion.

This is a good suggestion, thanks. Given our discussion on the copyright of these files, I am not sure that this would be acceptable for inclusion in Typst packages. (My very own interpretation of your packaging rules is that it is clearly okay to include the files as differently-licensed assets of the package, but only probably okay to expose them as templates.) If you converge on a decision on this aspect, and the decision is that offering these files as templates would be acceptable, then I will do as you suggest.

[gasche]

(Note: if the CI system has a github repository somewhere, and you think it would be reasonably feasible to tweak the rules to not-warn on all-caps argument names, which are probably acronyms and not CamelCase identifiers, then I could consider trying to contribute this.)

[elegaanz]

I think it would be fine to ship these two files as a template.

Regarding the CI system, the code is available here. Thank you for offering your help.

[gasche]

Thanks for the guidance! I updated the PR to offer second-proposal.typ as a template. (I think the second, longer document is marginally more useful to expose than the first, because it contains more section titles etc.)

[gasche]

The CI fails with an error because it considers second-proposal.png (the thumbnail) as a "compiled document". The code in package-check fails on foo.png if foo.typ also exist. I will silence the error by renaming the file as second-proposal-thumbnail.png.

[elegaanz]

The actual issue here is that files for the template should be in their own subdirectory. Only files in this directory will be copied when starting a project with typst init @preview/anr-aapg-fanmade. This will also allow you to ship the two files: just put them both in the template directory. The thumbnail should stay in the root of the project, and can be renamed to its original name if you want.

[elegaanz]

Hello! Do you think you will soon be able to fix the package structure as explained in my previous message? No worries if not, but I will then close this PR as inactive (you will just have to open a new one once you fixed the issue).

[gasche]

@elegaanz thanks for the ping. I updated the package following your recommendation, with a template subdirectory and both {first,second}-proposal.typ files inside it.

[typst-package-check]

@CL4R3T You released meppp:0.2.1, so you probably want to have a look at this pull request. If you want this update to be merged, please leave a comment stating so. Without your permission, the pull request will not be merged.

[typst-package-check]

@SillyFreak You released linguify:0.4.2, so you probably want to have a look at this pull request. If you want this update to be merged, please leave a comment stating so. Without your permission, the pull request will not be merged.

[elegaanz]

We're getting there, just one small thing about the thumbnails location, and it should be good to merge!

[elegaanz]

Thumbnail files should be outside of the template directory: this directory only contains files that will be copied to the user's project. The thumbnail key in the manifest is relative to the root of the package, not to the template directory.

[gasche]

Thanks! I also changed the thumbnails from .png to .webp, following the discussion in #2007 .

[gasche]

I believe that the bot messages come from the fact that I temporarily pushed a version of this PR sitting on top of some local experiments on mine regarding #2024, which removes duplicated files and replaces them by a symlink. Sorry for the trouble.

[elegaanz]

Thank you.