questions on fricas.github.io

[Qian Yun]

Hi Ralf,

1. This site is still for 1.3.10 version. I guess you are
too busy to update it?

I can give it a try to update for 1.3.11. I'll open a PR
for you to review.

2. The main reason is that I want the new reference book
to show in the documentation site.

I suggest to change the link from
https://fricas.github.io/book.pdf
to
https://github.com/fricas/fricas/releases/download/1.3.11/fricas-1.3.11-reference-book.pdf

So that the download statistics can be collected.

3. Is it worth the effort to automate the process of updating
this site? (via CI, github actions.)

4. Is it worth the effort to also have the documentation site
for the nightly code (git HEAD)?

- Qian

[Waldek Hebisch]

On Sat, Sep 21, 2024 at 07:24:37PM +0800, Qian Yun wrote:
> Hi Ralf,
>
> 1. This site is still for 1.3.10 version. I guess you are
> too busy to update it?
>
> I can give it a try to update for 1.3.11. I'll open a PR
> for you to review.
>
> 2. The main reason is that I want the new reference book
> to show in the documentation site.

I have put book pdf at:

http://wiki.fricas.org/public/book.pdf

and linked result of API build at

http://fricas.org/

(this also contains copy of the book).

> I suggest to change the link from
> https://fricas.github.io/book.pdf
> to
> https://github.com/fricas/fricas/releases/download/1.3.11/fricas-1.3.11-reference-book.pdf
>
> So that the download statistics can be collected.
>
> 3. Is it worth the effort to automate the process of updating
> this site? (via CI, github actions.)

I am not sure what trouble Ralf had. Above I had trouble: first
time documentation build failed. And I did not look if links
are correct. But IMO updating site is trivial provided that
documentation build works OK. So I would be for manual
update (this avoid potentially nasty troubles when automation
fails or is abused by malicious actors).

> 4. Is it worth the effort to also have the documentation site
> for the nightly code (git HEAD)?

I do not think so: changes are slow enough. I think that
automatically extracting _differences_ could be of some use.
But that would require some work.

--
Waldek Hebisch

[Qian Yun]

On 9/22/24 12:00 AM, Waldek Hebisch wrote:
> On Sat, Sep 21, 2024 at 07:24:37PM +0800, Qian Yun wrote:
>> Hi Ralf,
>>
>> 1. This site is still for 1.3.10 version. I guess you are
>> too busy to update it?
>>
>> I can give it a try to update for 1.3.11. I'll open a PR
>> for you to review.
>>
>> 2. The main reason is that I want the new reference book
>> to show in the documentation site.
>
> I have put book pdf at:
>
> http://wiki.fricas.org/public/book.pdf
>
> and linked result of API build at
>
> http://fricas.org/

I didn't noticed that this site has the updated version of API doc.

I think fricas.github.io and fricas.org/api should not diverge.

I take a look into the source file, seems that the links are all
internal, meaning that the same set of static files can be
deployed to both sites without modification.

> (this also contains copy of the book).
>
>> I suggest to change the link from
>> https://fricas.github.io/book.pdf
>> to
>> https://github.com/fricas/fricas/releases/download/1.3.11/fricas-1.3.11-reference-book.pdf
>>
>> So that the download statistics can be collected.

What do you think of this proposal? Removing the pdf from the site,
and putting a link to GitHub release page instead.

Currently the pdf files are bloating the repo
https://github.com/fricas/fricas.github.io
to over 77MB.

- Qian

[Waldek Hebisch]

On Sun, Sep 22, 2024 at 08:40:18AM +0800, Qian Yun wrote:
>
>
> On 9/22/24 12:00 AM, Waldek Hebisch wrote:
> > On Sat, Sep 21, 2024 at 07:24:37PM +0800, Qian Yun wrote:
> > > Hi Ralf,
> > >
> > > 1. This site is still for 1.3.10 version. I guess you are
> > > too busy to update it?
> > >
> > > I can give it a try to update for 1.3.11. I'll open a PR
> > > for you to review.
> > >
> > > 2. The main reason is that I want the new reference book
> > > to show in the documentation site.
> >
> > I have put book pdf at:
> >
> > http://wiki.fricas.org/public/book.pdf
> >
> > and linked result of API build at
> >
> > http://fricas.org/
>
> I didn't noticed that this site has the updated version of API doc.
>
> I think fricas.github.io and fricas.org/api should not diverge.

I just put the pages there. One reason was to check how well the
process works, as I wrote I had to build documentation 2 times,
first time documentation build failed. But together it was
few minutes of CPU time and maybe 30 seconds of manual work.

Concerning "diverge", IIUC github.io is limited to static pages.
At fricas.org we can install a generator for dynamic content,
so potentially we can have more things. But this depends on
what people doing work want to do. Anyway, installing update
on fricas.org is trivial. I assumed that the same holds
for fricas.github.io, at least for people doing this (for
me it is impossible task due to github security nonsense).

> I take a look into the source file, seems that the links are all
> internal, meaning that the same set of static files can be
> deployed to both sites without modification.

Except for the toplevel page (which is written by hand) other
pages at fricas.org are result of documentation build.

To say the truth, there is also some experimental stuff at fricas.org,
but there are no external links to it, so it is hidden from
normal visitors.

> > (this also contains copy of the book).
> >
> > > I suggest to change the link from
> > > https://fricas.github.io/book.pdf
> > > to
> > > https://github.com/fricas/fricas/releases/download/1.3.11/fricas-1.3.11-reference-book.pdf
> > >
> > > So that the download statistics can be collected.
>
> What do you think of this proposal? Removing the pdf from the site,
> and putting a link to GitHub release page instead.
>
> Currently the pdf files are bloating the repo
> https://github.com/fricas/fricas.github.io
> to over 77MB.

It is not clear to me what download statistics really mean. Namely,
for moderately used site most downloads is from robots. High profile
sites tends to deploy various anti-robot means. But IMO anti-robot
means are major inconvenience for normal users.

For source code archive one can hope that most robots will ignore it.
OTOH .pdf is much more likely to be downloaded by a robot.

--
Waldek Hebisch

[Qian Yun]

On 9/22/24 6:54 PM, Waldek Hebisch wrote:
>>
>> I think fricas.github.io and fricas.org/api should not diverge.
>
> I just put the pages there. One reason was to check how well the
> process works, as I wrote I had to build documentation 2 times,
> first time documentation build failed. But together it was
> few minutes of CPU time and maybe 30 seconds of manual work.
>
> Concerning "diverge", IIUC github.io is limited to static pages.
> At fricas.org we can install a generator for dynamic content,

Yes, I meant fricas.github.io and fricas.org/api should have the
same content. I noticed that you have fricas.org/index0.html.

>
> Except for the toplevel page (which is written by hand) other
> pages at fricas.org are result of documentation build.

That's good to know. So I'll try to update fricas.github.io.
And in the future, if https://github.com/fricas/fricas.github.io
gets updated timely, you can simply copy its content instead of
building the site yourself.

>>>
>>>> I suggest to change the link from
>>>> https://fricas.github.io/book.pdf
>>>> to
>>>> https://github.com/fricas/fricas/releases/download/1.3.11/fricas-1.3.11-reference-book.pdf
>>>>
>>>> So that the download statistics can be collected.
>>
>> What do you think of this proposal? Removing the pdf from the site,
>> and putting a link to GitHub release page instead.
>>
>> Currently the pdf files are bloating the repo
>> https://github.com/fricas/fricas.github.io
>> to over 77MB.
>
> It is not clear to me what download statistics really mean. Namely,
> for moderately used site most downloads is from robots. High profile
> sites tends to deploy various anti-robot means. But IMO anti-robot
> means are major inconvenience for normal users.
>
> For source code archive one can hope that most robots will ignore it.
> OTOH .pdf is much more likely to be downloaded by a robot.
>

There's download statistics in sourceforge. There's also download
statistics for github:

curl https://api.github.com/repos/fricas/fricas/releases/tags/1.3.11
| grep -E 'name|download_count'

"name": "Release 1.3.11",
"name": "fricas-1.3.11-full.tar.bz2",
"download_count": 115,
"name": "fricas-1.3.11-macOS-arm64-unsigned.dmg",
"download_count": 22,
"name": "fricas-1.3.11-macOS-x86-64-unsigned.dmg",
"download_count": 8,
"name": "fricas-1.3.11-reference-book.pdf",
"download_count": 77,
"name": "fricas-1.3.11-windows-x64.zip",
"download_count": 139,
"name": "fricas-1.3.11.amd64.tar.bz2",
"download_count": 32,
"name": "Notes-1.3.11.txt",
"download_count": 26,
"name": "sha256sum-1.3.11.txt",
"download_count": 8,

If we host the reference book in one location, then we can get a
more accurate statistics on how many people have downloaded the book.

- Qian

[Ralf Hemmecke]

>> 3. Is it worth the effort to automate the process of updating this
>> site? (via CI, github actions.)

> I am not sure what trouble Ralf had.

I just updated fricas.github.io. Well, my "trouble" is in an old setup
that still lies around and always confuses me. Releases are rare enough
to eventually get it right, but I wanted to check before I update.

There is, for example,

https://github.com/fricas/fricas/blob/master/src/doc/sphinx/source/citation.rst

it shows

@Misc{FriCAS,
key = {FriCAS},
author = {{FriCAS team}},
year = {2024},
title = {{FriCAS} 1.3.10---an advanced computer algebra system},
note = {Available at \url{http://fricas.github.io}}
}

with the wrong number. I would be happy if Waldek puts it on his list
"to do before releas" to update the version also in that bib-entry.

I think that is the only piece left, otherwise

cd builddir/src/doc; make doc

build already everything to be put into the fricas.github.io.git repository.

>> 4. Is it worth the effort to also have the documentation site for
>> the nightly code (git HEAD)?

> I do not think so.

I also don't think so. Using

cd builddir/src/doc; make localdoc

Anyone can get the documentation that even needs no internet connection
to browse through the api description. The book is anyway locally built.

I builld specifically, for fricas.org, I haven't investigated, but I
think it should be possible to do via "make doc" and setting a few

PACKAGE_...

variables before calling make. See here...

https://github.com/fricas/fricas/blob/master/src/doc/Makefile.in

> Currently the pdf files are bloating the repo
> https://github.com/fricas/fricas.github.io to over 77MB.

I do not care much about the size of the fricas.github.io.git
repository. I try to keep it small, but I actually want to also record
the exact state as it was when I uploaded it (for historical reasons).
And 100MB is not something that I find too trouble making when it
contains already 14 releases.

> If we host the reference book in one location, then we can get a more
> accurate statistics on how many people have downloaded the book.

Well, I would also like to know how many people actually use FriCAS (it
would be a kind of motivation---maybe also for other developers), but I
think that the download statistics is only a very rough measure to get
such a number. Maybe we can encourage our users to send feedback to us
even if there are no problems to solve.

Ralf