oscar-system/oscar-website

Dev repo for the oscar website

oscar-website's Issues

Merging #95 did not update the website

Provide instructions how to take Julia-Oscar Jupyter notebooks and run them locally

We need to improve the example page by giving instructions somewhere how one can download these notebooks and get them to run locally. That includes installing Oscar.jl (we already describe this), but also IJulia. Finally, how shall the user "load and run" that notebook.

Note that notebooks may have further requirements beyond Oscar and IJulia. Perhaps we can or should change https://github.com/oscar-system/OSCARBinder to have a Project.toml (or perhaps multiple, one for example: move the examples into a subdirs, with their own Project.toml. Perhaps even with a Manifest.toml; I don't know, figuring this out is part of the job).

@rfourquet we (the OSCAR PIs) thought that maybe you could work on that, given that you are Julia expert. I don't know if you know anything about IJulia; but in a sense, if you don't, that might make you even more perfect for this... ;-)

Sort the examples differently, perhaps group them into categories

The examples should come in a different order: first there should be basic examples ; then more advanced ones. We could also group things into categories.

To decide what is basic and what is not, as a first approximation, you could do this: Open the notebook; if you immediately understand what's going on (and it's not just because it's your personal area of expertise), it's basic; if not, then it is probably not (it might be basic in its area, but not "basic" in a global context).

We can of course refine and change later on what is "basic" and what is "advanced", resp. what is which category; the important bit here is to create infrastructure so that we can group things this way, and to have an initial on this.

Related to issue #92

Documentation: Installation under Windows

I have managed to install Julia under Windows as described in the documentation. I have minor suggestions to make things more clear:

In the first item it is said: Search for "Turn Windows features on or off". I first wondered: search where? Maybe you could add to search in this task bar thingy, whatever the correct name is. Is there a keyboard shortcut for the search?

In item 5 you it is said: Click the Windows store icon. I had to search for this as well, there was no shopping bag (maybe I removed it already, I can't remember).

I use Windows 11 and my installation wasn't that old but after starting Ubuntu from the App Store I received an error message telling me I need WSL2. It came with a link to https://learn.microsoft.com/en-us/windows/wsl/install-manual#step-4---download-the-linux-kernel-update-package. So maybe this should be added as another step.

Edit: Search shortcut is Windows Key + S and the thingy is indeed called taskbar (reference).

Edit: I ran into a pitfall when doing apt-get update as described in the installation step 1 for Ubuntu. It said "Release file...not ready yet". With some googling I found this: the clock in WSL2 seems to be wrong sometimes. This can be fixed with sudo hwclock --hctosys . After that, the installation worked.

"Call Singular from GAP" notebooks do not work (anymore)

The code in the notebooks

https://nbviewer.jupyter.org/github/oscar-system/OSCARBinder/blob/master/GAPJulia_Singular_car.ipynb

and

https://nbviewer.jupyter.org/github/oscar-system/OSCARBinder/blob/master/GAPJulia_Singular_blog.ipynb

provided by @ThomasBreuer does not work anymore with recent versions.

"Citations of Oscar and its components" should include at least years

Add more example notebooks

I think all examples that are tested on https://oscar-system.github.io/oscar-ci-status/ should also be shown on the website in the examples (@micjoswig @fieker @wdecker can speak if they disagree).

@rfourquet please take care of that; there are links to the notebook in this CI dashboard, but you can also ask @rbehrends about where to find them etc. Probably also a good if @rbehrends notifies @rfourquet (and vice versa) about new examples?

Add "Edit this page" links to pages

@rfourquet

install.md: re-enable "Starting GAP with JuliaInterface" ?

At the end of install.md, there are commented out GAP-related instructions:

~/.julia/gap.sh

and

LoadPackage( "JuliaInterface" );

Can this TODO be done, now that the issue is closed?

TODO: disabled until oscar-system/GAP.jl#335 is resolved

On my system this file "~/.julia/gap.sh" is not present.

cc. @fingolfin

Make Install page aware of user's OS, focus the relevant instructions

... so that e.g. Windows user are immediately told to first install WSL, then install Julia in there

Add more news items related to GAP work

... in particular to GAP.jl ; I'll try to add some stuff in the next week.

In the meantime, maybe @frankluebeck and @ThomasBreuer also have things they'd like to mention here, on the GAP and Julia related work they've been doing as part of the SFB?

Our Slack should be mentioned on website

... on https://oscar.computeralgebra.de/community/ with brief explanation what it is / what is good for, and how to join (right now that means: "please email to... (??? perhaps me?) and we'll give you an invite. We'd like to automate this but this is a bit tricky"

@rfourquet can you prepare a draft for such a thing?

Add all the missing talks from 2019 and 2020 -- and possibly disable the "Talks" page until we have any

We currently only listed a single talk for 2019, which looks really bad. Luckily, it's also wrong, there were talks.

I believe it is the responsibility of the PIs and the people employed by the SFB to fix this, by (a) adding their talks, and (b) encouraging other people they know who talked about OSCAR to add theirs, too.

To do so, you can edit the file https://github.com/oscar-system/oscar-website/blob/gh-pages/_data/talks.yml which is fairly straight forward. If anything is unclear, though, don't hesitate to ask.

In the meantime, unless we can very quickly populate this, I think we should disable it for the time being. Better to list no talks than this outdated list. See PR #73

Add warning that a OS and compilers newer than 2017 are needed

... as Singular.jl via CxxWrap.jl requires C++17 and a cmake which has C++17 support; so e.g. Debian 16.04 won't work.

Proposal: merge "Blog" into "News"

There seems little reason to keep these separate, and it slightly reduces the issue of either of them having not too much in there.

Note that if we do so, we should make sure that the old blog URLs redirect to the new location.

Elaborate on Julia install instructions? At least for mac users...

The Julia download page is not great; it has now browser OS detection, so the user has to find the right binary; and in any case, first there is a wall of text before the first download link (and on an Apple device, that wall maybe all one can see without scrolling, and Apple in their eternal wisdom by default hides the scrollbars). Of course if one reads that text, one will discover the download eventually, but it takes some time.

Plus on a mac, then people may not know how to proceed (drag Julia.app into the "Applications" dir.... agree to the scary warnings Apple shows.... etc.).

Perhaps we should in fact implement a "Browser switch" and show specialized instructions if we detect a Windows/Apple/Linux system (of course the other instructions should still be one click away).

Set up fixed URL for signing up to Slack

The Slack invite link is "permanent" in theory, but in practice it sometimes changes. Whenever that happens, any text or website referencing it becomes outdated.

To solve this, I suggest we create a fixed URL like https://slack.oscar-system.org or https://oscar-system.org/slack-invite which redirects to the then current invite URL. Then we can reference this fixed URL everywhere, and just update a single point if necessary.

Provide updated install instructions

Update website to show new webmaster email address

@rfourquet this is for you (I can't assign it to you yet as you need to accept the invitation to oscar-system first).

Add prominent link(s) to the Oscar.jl github

It is rather difficult to find links to https://github.com/oscar-system/Oscar.jl on https://oscar.computeralgebra.de/ ; there is one on https://oscar.computeralgebra.de/community/ and that's essentially it.

I suggest two things:

1. Add a "Fork me on Github" decoration on the top right like on https://tmate.io and many other pages
2. add it to the nav menu

Update contributors list

Add information on "how to cite Oscar"

On the long run, we hope to have a paper / book that one can use for that. In the meantime, we might still want to suggest some bibtex template that people can copy and past, to get at least some structure into that.

PIs should make a suggestion for that, I just wanted to now it down here right now so I don't forget about it again

add NEWS for HomalgProject

HomalgProject.jl doesn't appear in the homepage of the website, but is mentioned in the documentation and community pages, maybe a News item is warranted for its releases? cc @mohamed-barakat

Add CI tests for the examples

The examples we provide, including Jupyter notebooks, should undergo CI tests to ensure they are still working; of course that also means we need to watch out for those CI tests and fix notebooks (resp. fix the package(s) that caused the regression.

See also issue #63 ; I also think @ulthiel spotted some broken examples.

Add info about polymake prompt to install page?

We describe the GAP prompt; now that there is a polymake prompt (triggered via $), perhaps we should describe that, too?

Fix webmaster email

on the left side-panel, "contact webmaster" gives the email [email protected]
which seems to not be valid.

Move Oscar.jl docs to be first on the Documentation web page

Broken link for the Factory software

At https://oscar.computeralgebra.de/credits/, the link for Factory is ftp://www.mathematik.uni-kl.de/pub/Math/Singular/Factory, which currently doesn't work (since at least a few days).
I'm not sure who can fix that, so I will tentatively ask @hannes14 ?

Cryptic error messages without build-essential

When the user installs OSCAR on Ubuntu or Debian and forgets to install build-essential, they will have strange error messages. Perhaps it would be better to check whether build-essential is installed (meaning, whether specific C files exist that OSCAR uses) and if not, give instructions to install it.

Improve Windows install instructions

For Windows users, our install instructions are lacking: we do tell them to install WSL, but then not how to use that. In particular, when they get to step 2, it is not clear that they need to download the Linux binaries (and then what to do with them!) so naturally they may end up downloading the Windows binaries, which is wrong, but hard to understand.

We should improve this. E.g. by editing Step 2 to explicitly separate between Windows and non-Windows users, and providing more details for the former.

Alternatively, we could have the Windows instructions completely separate from the Unix one. I am open to either, as long as it is clear for Windows users.

Michael also suggested that it might be also helpful to add screenshots to illustrate the process, which indeed seems useful.

Add instructions to install Oscar in a docker container running ubuntu

I suggest adding the following instructions to prepare a docker container running Ubuntu (ubuntu:latest) for installing Oscar:

In the container run

apt-get update
apt-get install curl wget autoconf make g++ julia libjulia-dev

Example page looks corrupted on brave browser

Meeting pages: improve top nav bar

On meeting pages like https://oscar.computeralgebra.de/meetings/2022-02/ we should a nav bar at the top for the various subpages. This could be improved in various ways:

• highlight the currently active page
• render it nicer
• allow for an order other than alphabetical (?)

Code blocks are too narrow

And linebreaks are confusing. E.g. at https://rfourquet.github.io/oscar-website/install/ , section "Ubuntu 16.04 "Xenial":

Come up with a nicer way to display the examples

The examples display on https://oscar.computeralgebra.de/example/ does not look so nice. This needs to be improved; and once we have more examples, we must also think about how to make this more accessible. Some thoughts and ideas (to be refined, i.e. none of this is set in stone):

• perhaps the examples could be narrower, but then two side by side? (Perhaps a responsive design with "cards" a bit like on https://oscar-system.github.io/oscar-ci-status/index.html could be used?)
• assign "keywords" or "tags" to each example, e.g.: "GAP, Singular, tropical matroids" which give a rough indication which technologies and mathematical areas are in the example (@rfourquet shall provide the setup, but others can and should help with determining what tags are appropriate)
• once there are many examples (I wish...) we can think about allowing to filter the displayed examples by tag (e.g. "only show examples with tags "GAP" and "tropical" or so)
• .. more? Not sure

Automate news items for package releases

@lkastner made the PR #317 using this Perl script, saved as scrape.pl in news/_posts/ and run from inside that directory:

#!/usr/bin/perl

use strict;
use warnings;
use JSON;

# Sample usage:
# perl scrape.pl oscar-system/Singular.jl 0.14.0 0.16.0
# perl scrape.pl oscar-system/Polymake.jl 0.8.1 0.8.3
# perl scrape.pl oscar-system/Singular.jl
# perl scrape.pl oscar-system/Polymake.jl

my $name = $ARGV[0];
my $upper = $ARGV[2];
my $lower = $ARGV[1];
my $all_selected = 0;
if(!defined($lower)){
   $all_selected = 1;
}
if(!defined($upper)){
   $all_selected = 1;
}
print "name is $name $lower -- $upper\n";
my($progname) = $name =~ m/\/(.*)/;
my $filename = "$progname-release.md";
print "Will use filename $filename\n";

my $current = `curl https://api.github.com/repos/$name/releases`;

my $json = JSON->new->allow_nonref;
my $perl_scalar = $json->decode($current);
foreach my $v (@$perl_scalar){
   my($version) = $v->{"name"} =~ m/v(.*)/;
   if(defined($version)){
      if((version_compare($lower,$version)> 0 && version_compare($version, $upper)<=1) || $all_selected){
         print "$version selected\n";
         write_file($filename, $progname, $v);
      } else {
         print $version," not selected\n";
      }
   }
}


sub write_file {
   my($filename, $progname, $v) = @_;
   my($version) = $v->{"name"} =~ m/v(.*)/;
   my $body = $v->{"body"};
   print "$body\n";
   my $date = $v->{"published_at"};
   ($date) = $date =~ m/(\d\d\d\d-\d\d-\d\d)/;
   ($body) = $body =~ m/(\[Diff.*)/ms;
   if(!-e "$date-$filename"){
      open(my $fh, ">$date-$filename");
      print $fh <<"%%%";
---
layout: post
title: $progname $version released
author: TagBot
---

Today [$progname $version](https://github.com/$name/releases/tag/v$version) has
been released.

$body
%%%
      close($fh);
   }
}


sub version_compare {
   my($v1, $v2) = @_;
   if(!defined $v1){ return 1; }
   if(!defined $v2){ return 1; }
   print "v1:$v1 v2:$v2\n";
   my($v1major, $v1minor, $v1patch) = $v1 =~ m/(.*)\.(.*)\.(.*)/;
   my($v2major, $v2minor, $v2patch) = $v2 =~ m/(.*)\.(.*)\.(.*)/;
   if($v1major < $v2major) { return 1; }
   if($v1major > $v2major) { return -1; }
   if($v1minor < $v2minor) { return 1; }
   if($v1minor > $v2minor) { return -1; }
   if($v1patch < $v2patch) { return 1; }
   if($v1patch > $v2patch) { return -1; }
   return 0;
}

It would be nice if we had a GH Action that run this script or something equivalent to query all our packages for updates, and if there are any, open a PR (e.g. using https://github.com/peter-evans/create-pull-request) with the new stuff. Or even just directly apply the updates, whatever.

Of course one could also improve it. E.g. the automatic release notes provided by GitHub reference pull requests and issues by number. It would be nice if those were actual hyperlinks in the news items.

Improving meetings pages: top navigation

Right now navigating meeting pages and subpages IMHO is confusing and not very smooth.

I think it would help if each meeting page like http://oscar.computeralgebra.de/meetings/2021-09/ had at the top another (horizontal) navigation bar which just gives the subpages, clickable. So in that example:

Overview | Participants | Program | Registration

Then we can remove the corresponding entries from the left side navigation bar, which already is rather crowded.

Restore automatic updating of the page

With the new webserver, automatic updating of the website broke. I.e. right now, it is not sufficient to just commit to the gh-pages branch resp. merge PRs, one also has to update the webserver. If the need arises, contact me and I'll do it ASAP.

But really, the automatic needs to be restored. This is not a big issue, I simply need to find the time for it. So in the meantime, I am logging this issue so that others are aware of it, and also to remind me.

Better install instructions for Windows users

1. say more precisely which Julia binary to download ("look for Linux 64bit glibc"), or even better, provide a direct download link
2. say how to actually download the result inside WSL
3. say how/where to extract it so that the user can access it from anywhere ("add it to PATH")
4. alternatively to the above: suggest a "one click install method" if there is one (probably not...) or at least one that is simpler; e.g. it might be easier to tell people something like sudo apt-get install python3 && pip3 install jill --user -U && jill install or so (to be tested!!!!)
5. It would be great to have a way to add an icon to the desktop or start menu which users can select to start a Julia session (inside WSL), or even an Oscar session

Examples are outdated; update them, possibly remove some; add new ones

Better install instructions for macOS ; On macOS 10.14, installing Xcode via App Store doesn't work

The App Store only offers to install the latest Xcode version but then refuses to install it because it requires macOS 11... So yeah.

Not sure what the best fix is. Perhaps we can just point people on older macOS versions directly to the command line tools download (which we eventually got from https://developer.apple.com, but it was surprisingly difficult to find (we had to click on "Downloads", which only showed "TestFlight"... finally a super tiny "more" links at the top right lead us to it... Version Xcode 11.3.1 is the latest for macOS 10.14 Mojave.

This sucks, Apple!

Install instructions should use apt

The install instructions for Ubuntu or Debian should use apt, not apt-get. The Debian manuals say "The most recommended interface, apt, is the one that we will use in the examples given in this section".

add NEWS for GroebnerBasis.jl

@ederc Would be be willing to add a news item for the 0.1.0 release of GroebnerBasis.jl?
(cf. https://github.com/oscar-system/oscar-website#how-to-contribute-a-news-post).

Also GB.jl has been renamed to GroebnerBasis.jl right? If so I will update the website accordingly.

Suggestion: generate part of install page from a script

During GAP Days Fall 2018, @sebasguts @ThomasBreuer and me looked at https://oscar.computeralgebra.de/install/ and noticed that the instructions there are still based on Julia 0.6.3, so not even 0.6.4 and certainly not 0.7/1.0.

Having these instructions in a runnable shell script (which a user could perhaps download) would make it easy to test them; that script could also perhaps be used as part of the generation of an OSCAR Docker image.

That of course means that now you have to keep that script with the website in sync. So the following suggestion was made: the text on the website could be generated from that script. Essentially, comments in the script could be turned into text, and the code between comments into code blocks. That way, the instructions are always in sync with the script, and if the script is used to generate a docker image, also the docker image is automatically in sync. And this way, the instructions are constantly tested, and don't risk getting out of date.

Not mentioned what OSCAR stands for

Trivial suggestion: add a link to the website in the repo header

Examples and example notebooks on the website ought to be CI tested

The exact details on how we do this can vary, but we really need to do it in some way

Make sure all example notebooks start with `using Oscar` (or have a very good reason not to)

Please go through all example notebooks; for any that is not using Oscar, please contact the respective authors and work with them to get the notebooks update. (For the one authored by Sebastian Gutsche, I think we need somebody else to take over as "maintainer", as Sebastian left to academia).

Such a conversion can use the fact that Oscar imports the other cornerstones, so usually this should be a relatively minor change.

Add "Computing polynomial bases 1" notebook

The notebook at
https://nbviewer.jupyter.org/github/johannesflake/polybases-examples/blob/master/polybases-ex-1.ipynb
has been provided by Johannes Flake and shall be added to the Examples page.
Apart from the repository, the entry for _data/examples.yml can be as follows.

- title: "Computing polynomial bases 1"
  repository: ...
  filename: polybases-ex-1
  author: Johannes Flake
  thumbnail: oscar.png
  language: julia

Provide workaround for crash with Xcode 11.4 / macOS 10.15

here are crashes when using CxxWrap on macOS 101.5 with Xcode 11.4, which thus affects Polymake.jl and Singular.jl. Relevant issues:

• oscar-system/Oscar.jl#82
• JuliaInterop/CxxWrap.jl#230

Luckily @benlorenz came up with a workaround.

This should be added to the website until we have a proper fix -> @rfourquet please take care of that, in coordination with Benjamin (who knows the details), and perhaps @mo, who can test the instructions

Of course once a "proper" fix is available, we then should remove these instructions again.