Prepare the book website

[fingolfin]

Some time ago we set up a placeholder for the book website at https://book.oscar-system.org

I think we should start filling it with some life. My vision would be: have a subpage for each chapter of the book. On there, perhaps provide the code from the books in a form that users can somehow access (be it as .jl files, or code you can copy&paste into a Julia REPL, or Jupyter notebooks, or ...)

We can then also email all book chapter authors to ask them if there is additional content they want to have added to those pages.

[fingolfin]

One simple way to make the code available could be to just start with the .jlcon files and show them inside of code blocks. Book chapter authors can make further edits to them if they like.

To be clear: my idea here would be that one person does this initially, taking those files from the book repository and setting up an initial book website, with subpages for each book chapter. The result won't be perfect, but it's a starting point. Once we have this, book chapter authors can improve their respective subpages as they deem fit.

I'd keep this very simple for now:

1. create a top index page which has an enumerated list of all chapters, listing their titles and authors. The titles are hyperlinks to subpages (e.g chapter_05.md so you don't have to think about fancy file name).
2. in each subpage add a title and again the author names, and dump in the code
3. bonus points for setting up some javascript or so to add a little "copy to clipboard" link to each code block.
4. then the book chapter authors can have their way and improve their pages. But they don't have to worry about what to put where etc., we already provide a framework

Of course this setup won't automatically update code blocks to match the output of newer OSCAR versions. I think that's OK. We could just add at the top of each chapter page something like: "The output below is exactly as in OSCAR 1.0" (and then if we update a chapter page to a newer OSCAR version, just mention it there).

If someone wants a more fancy setup with CI that updates outputs, fine by me, but unless you can do it right now, let's wait with implementing such things; first have something presentable, then if you want and have the energy, worry about more fancy solutions.

[fingolfin]

(Oh and once the book is out and has an URL/DOI etc., we should of course add that too)

[fingolfin]

Another matter is: we could update the look of the book page to differentiate it more from the regular OSCAR page. E.g. use a different color for the navbar? Or even the logo? Perhaps the book has a nice title page, then we could use a little rendering of that instead of the OSCAR logo? And replace "The OSCAR project" in the navbar by e.g. "The OSCAR book" or whatever.

And of course there should be links to the book page from our website and README.md and elsewhere, and the book page should have links to the OSCAR website and possibly other locations

[fingolfin]

Perhaps @aaruni96 and @HereAround can work on this?

[lkastner]

At some point I asked some questions about this on Slack. So I take it that I am out?

[fingolfin]

@lkastner absolutely not, I am happy for you to work on this, too!

[fingolfin]

(or anyone else, for that matter! It's just that if I don't name any names, in doubt nobody will work on it? :-) )

[fingolfin]

We just (re-)discovered by https://github.com/oscar-system/OscarBookExamples.jl/ by @benlorenz -- great! perhaps if this works and is usable right now it could be used to populate the chapter pages, perhaps in a better way than the "simple" modle I sketched above?

Look, I am totally open to other approaches, which is why I opened an issue instead of just telling somebody to do something: here we can discuss approaches and coordinate how to implement them. And then get it done, it shouldn't be that much work for the initial setup, I think?

[lkastner]

We already talked about this at some point. OscarBookExamples.jl is just a script for extracting the examples. These can then be collected as md files. The question was now whether these md files should go up on the website or whether they should be converted to something else e.g. like jupyter. I also asked for a concrete folder where I should put stuff.

[fingolfin]

For now the examples could go into some subdirectory of https://github.com/oscar-system/book.oscar-system.org -- maybe for starters call it examples, and perhaps have one subdirectory of that per book chapter? Say examples/chapterNN (and examples/introduction) ?

We can then still move them elsewhere if we have a better idea later on.

In what format would those examples be then?

So far I though we would just put the raw .jlcon files in there, and include them from main chapter pages chapterNN.md, but if you have a better idea, great!

[thofma]

Whatever the automatic process does, I think it should not be made the official version without the authors giving their "yes". The code blocks without the text have the potential to be quite confusing.

[lkastner]

Whatever the automatic process does, I think it should not be made the official version without the authors giving their "yes". The code blocks without the text have the potential to be quite confusing.

What does this mean? I should not upload something?

Also how do we envision usage? I thought that this is for someone who has the book and is to lazy to type everything, or for someone who has the book in ten years and now stuff works differently.

[thofma]

Sorry, I reread the proposal and I think I misunderstood something. Ignore my comment.

[aaruni96]

@lkastner can you upload all the md files in a folder (call it anything for now, it doesn't matter) onto the book website repo ?

[fingolfin]

Closing this here -- further requests for improving the book website should be made at its issue tracker https://github.com/oscar-system/book.oscar-system.org/issues