FriCAS WWW

[Waldek Hebisch]

I am thinking how we should organize FriCAS information on
the web. s I wrote, I think that wiki plays role. OTOH
using wiki as IssueTracker has serious problems. One of
problems is that once issue is fixed in FriCAS regenerating
page erases examples of buggy behaviour and replaces them
by fixed result. There are other problems, so we should
not enter new bugs into IssueTracker. But it makes some
sense to preserve old reports, some issues are still open
and some closed issues contain explanations. I think
that we should convert IssueTracker pages to static form.
So pages will be no longer really part of wiki. This
has advantage that I will be able to do some edits
to correct say links, but preserving specimens of buggy
behaviour.

There is more to FriCAS presence on the web. ATM I put
at fricas.org minimal project page. I wonder I you
have some ideas what should we add there?

--
Waldek Hebisch

[Qian Yun]

Most importantly, documentation should be put there.

Also there shall be a "news" section, or "past release" section.

There shall also be a "developer" section on how to participate
in development of FriCAS.

And a section that shows examples of most common usage of FriCAS.

Shall fricas.org be synced to fricas.github.io somehow?
Shall fricas.org source code be managed under git?

- Qian

[Ralf Hemmecke]

Since I currently put up the stuff at fricas.github.io, it actually
needn't be me.

On 23.09.23 09:47, Qian Yun wrote:
> Most importantly, documentation should be put there.

Definitely, my suggestion would be that we simply serve the pages from

https://fricas.github.io

from https://fricas.org. And that would be completely easy to do.

The pages at fricas.github.io are generated from our official fricas git
repository. Since sphinx-doc is involved the result is basically pure
html, no fancy content management system needed.
OK, the generation of the book requires latex, and imagemagick and a few
other things, but that's easy to setup. Otherwise only python3 and
sphinxdoc must be installed.

> Also there shall be a "news" section, or "past release" section.

That we can add to this page:
http://fricas.github.io/download.html

> There shall also be a "developer" section on how to participate
> in development of FriCAS.

Is already there, but might need to be expanded.

http://fricas.github.io/development.html

> And a section that shows examples of most common usage of FriCAS.

http://fricas.github.io/examples.html

That should also contain more stuff... Contributions welcome.

> Shall fricas.org be synced to fricas.github.io somehow?
> Shall fricas.org source code be managed under git?

I can do it today, it is only a matter of setting some parameters.

https://github.com/fricas/fricas/blob/master/src/doc/sphinx/source/conf.py#L26

Well there is only one problem.
First we must decide whether we want the website fricas.org to be in
sync with the latest release or whether it should be in sync with the
git repository. Other ideas?

Ralf

[Waldek Hebisch]

On Sat, Sep 23, 2023 at 03:47:02PM +0800, Qian Yun wrote:
> Most importantly, documentation should be put there.

Yes, clear.

> Also there shall be a "news" section, or "past release" section.

On Sourceforge front page there is "news" part. I practice
almost all news are about releases. I wonder if you
imagine something like that or rather separate page.
In HyperDoc we have cumulative "news" part, with some work
we could get html version.

> There shall also be a "developer" section on how to participate
> in development of FriCAS.
>
> And a section that shows examples of most common usage of FriCAS.

Under wiki page FriCASLibraryExamples I collected a bunch
of examples. But ultimately there is question who wants
to write examples and how many.

> Shall fricas.org be synced to fricas.github.io somehow?

I think they should be "unified", that is give consistent
view.

> Shall fricas.org source code be managed under git?

That is not entirely clear to me. When there are scripts
which generate pages, like in API case using git is natural.
OTOH, for handwriten html benefits of version control are limited.
It makes sense to put all sources under version control for
uniformity, but I am not sure if we should insist on this.


--
Waldek Hebisch

[Waldek Hebisch]

On Sat, Sep 23, 2023 at 02:23:04PM +0200, Ralf Hemmecke wrote:
> Since I currently put up the stuff at fricas.github.io, it actually needn't
> be me.
>
> On 23.09.23 09:47, Qian Yun wrote:
> > Most importantly, documentation should be put there.
>
> Definitely, my suggestion would be that we simply serve the pages from
>
> https://fricas.github.io
>
> from https://fricas.org. And that would be completely easy to do.

That would be easy, but I am affraid rather unsatisfactory. I mean,
API pages and PDF of FriCAS book are good things. But there are
only handful of other pages at fricas.github.io, I hope that we can
create more. Part of my question is to find out what is desirable
and possibly if there are persons willing to add something

> The pages at fricas.github.io are generated from our official fricas git
> repository. Since sphinx-doc is involved the result is basically pure html,

Well, html and Javascript. IIUC search does not work without
Javascript.

> no fancy content management system needed.
> OK, the generation of the book requires latex, and imagemagick and a few
> other things, but that's easy to setup. Otherwise only python3 and sphinxdoc
> must be installed.

sphinxdoc and python3 are somewhat problematic dependencies. Namely,
much of Python world is unstable, that is changes in incompatible
ways in rather short timeframe. We already had problems that
version of sphinxdoc that you use was incompatible with my
system and version I had did not work with your sources.

Also, batch regeneration may be OK for slowly changing things
or things tied to specific release. But I defintely do not want
to delay updates to FriCAS website waiting for release.
When page is really pure html I can update it using text editor
and immediately see results, not so with batch update.

To put it differently, batch update is fine for "official"
documentaion. But it would be useful to have less
"official", more informal documentation.

In ideal world we would first think about logical organization
of material that we want to present, and then think about
technology needed to do this. But I am affraid part of
problem is that there are different technologies and
they do not cooperate very nicely. And people get attached
to specific technology they use, so effort gets fragmented.

> First we must decide whether we want the website fricas.org to be in sync
> with the latest release or whether it should be in sync with the git
> repository. Other ideas?

Official documentation should be with sync with latest release.
But other parts not, we should update them independently.

--
Waldek Hebisch

[Dima Pasechnik]

you can always pin down versions of python3 and its packages such as sphinx etc, by no means you must be on the latest versions

Also, batch regeneration may be OK for slowly changing things
or things tied to specific release.  But I defintely do not want
to delay updates to FriCAS website waiting for release.
When page is really pure html I can update it using text editor
and immediately see results, not so with batch update.

To put it differently, batch update is fine for "official"
documentaion.  But it would be useful to have less
"official", more informal documentation.

In ideal world we would first think about logical organization
of material that we want to present, and then think about
technology needed to do this.  But I am affraid part of
problem is that there are different technologies and
they do not cooperate very nicely.  And people get attached
to specific technology they use, so effort gets fragmented.

> First we must decide whether we want the website fricas.org to be in sync
> with the latest release or whether it should be in sync with the git
> repository. Other ideas?

Official documentation should be with sync with latest release.
But other parts not, we should update them independently.

--
                              Waldek Hebisch

--
You received this message because you are subscribed to the Google Groups "FriCAS - computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fricas-devel...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/fricas-devel/ZRDM9hC4mVYjICgk%40fricas.org.