Michael Soegtrop (Sep 28 2021 at 15:59): Michael Soegtrop (Sep 28 2021 at 15:59):@Enrico Tassi : the snap description limitation of 4096 chars really ****s. Do you know someone influential one could try to convince that this is nonsense? More or less for every package I add I have to reduce the trimming length by 5..10 chars - the shorter it gets the more effect it has since more package texts are trimmed :-) or :-( . Meanwhile the trimming hurts because some descriptions start with "This package contains a coq plugin which ....". Do you think we should try to get the synopsis down in opam or request a separate synopsis file?
@Karl Palmskog : FYI : there is an issue with the snap description which lists the synopsis of all included packages. But some smart head thought it would be a good idea to limit the length of a snap package description to 4k.
@Enrico Tassi : or should we include a link to some Coq Platform release information page instead? Having to cut away the license info ****s.
Théo Zimmermann (Sep 28 2021 at 17:07):I suggest not fighting with the limit and linking to an external page instead.
Michael Soegtrop (Sep 28 2021 at 17:53):@Théo Zimmermann , yes indeed I think this is the best. From the Mac installer we have a script which creates reasonably nice HTML code, but I think I would change it to create markdown and then use it to create these pages. There is some open enhancement issue in Coq Platform which I think shows how to do folding in github markdown - need to check.
Théo Zimmermann (Sep 28 2021 at 17:54):You can use standard HTML summary tags to do that.
Enrico Tassi (Sep 28 2021 at 19:03):I think we should make a page, either HTML or wiki or a release on GH, with all relevant infos and point there. Given there is a script (for osx) already, I think using gh pages is an option. See https://pages.github.com/ , I use it for the doc of coq-elpi and is very easy, you can also have CI push there for example.
But yes, 4K text v.s. 40M video is very silly.
Enrico Tassi (Sep 28 2021 at 19:50):I think that having https://coq.github.com/platform/$tag be a page with a human readable list of contents of $tag and have that URL linked by the snap package is not so bad. This is what I do to get updated doc in coq-elpi: https://github.com/LPCIC/coq-elpi/blob/d4b08dcdfedc176d79d1d131fe0bc84f8dfcb911/.github/workflows/doc.yml#L41-L51
Enrico Tassi (Sep 28 2021 at 19:51):This publishes (the doc generated by) every commit on master.
Enrico Tassi (Sep 28 2021 at 19:52):it makes a new commit with the contents of doc/ in a special branch which is then served via http by GH.
Karl Palmskog (Sep 28 2021 at 19:57):my advice would be to fully list the, say, "top" 10 packages of the platform with descriptions in the Snap description and link elsewhere as Théo suggests for the whole list. I think it would be sad if no packages at all are mentioned directly.
Théo Zimmermann (Sep 29 2021 at 06:52):If you list just their names, without a description, this should also be sufficient to be under the text limit, right? So then the question becomes do we give a sub list with description or a full list without description.
Michael Soegtrop (Sep 29 2021 at 09:32):In general I will follow the web approach, but maybe not for 2021.09. The exact details we need to discuss. I will base it on the OSX script.
I wouldn't list only top packages, because it is hard to judge which are the top packages.
I still think it would make sense to ask the package maintainers for a short (40 chars or even 30 chars max) description of their packages. The question is how we handle this technically. The options are to change the opam synopsis, to have a "synopsis.txt" file in the projects or to have a shell script with a table in Coq Platform.
Théo Zimmermann (Sep 29 2021 at 10:28):Opam packages already have the synopsis and the description field. I don't think it would really make sense to add a third field. I disagree that 30 characters descriptions would be useful beyond the package title. Furthermore, it wouldn't even scale if we continue adding packages...
Théo Zimmermann (Sep 29 2021 at 10:28):Listing all packages without the synopsis + a link to a webpage with a more detailed description sounds like the way to go to me.
Michael Soegtrop (Sep 29 2021 at 10:36):@Théo Zimmermann : yes, I tend to agree. So the conclusion is that I add just the list of opam package names (without the coq- prefix) plus a link to a page similar to the maxOS installer ReadMe file.
Théo Zimmermann (Sep 29 2021 at 11:00):Sounds good.
Last updated: Jun 03 2023 at 05:01 UTC