many broken links at https://fricas.github.io/examples.html

[Nasser M. Abbasi]

fyi, when I was browsing help on Fricas, I noticed many links do not work on

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

The first link works, but few I tried after that are all broken.

--Nasser

[Ralf Hemmecke]

> The first link works, but few I tried after that are all broken.

Sorry, my fault.

Replace in

http://fricas-wiki.math.uni.wroc.pl/FriCASIntegration

fricas-wiki.math.uni.wroc.pl

by

wiki.fricas.org

so you get (https)

https://wiki.fricas.org/FriCASIntegration

I will regenerate the pages as soon as I can.

Ralf

PS: I am just trying to give you some answer to your "op" question.

[Aravindh Krishnamoorthy]

Dear Ralf,

This is my first post on this group.

I'm a FriCAS user since a while and recently introduced FriCAS to a few colleagues who are hackers (i.e. familiar with Mathematica, Python, Git, etc.). Unfortunately, the entry bar is still quite high. IMHO this is largely due to the incoherent and unmaintained documentation, especially the "install" and "examples" sections of the website. Sorry; I understand that this project is a community effort and everyone's doing their best. But, the documentation definitely needs some improvement.

I wanted to submit a PR to fricas/fricas.github.io: FriCAS documentation but noted that the actual sources are scattered across "_sources", the repository fricas/fricas-doc: Sources for documentation part of https://fricas.github.io and other repositories. Furthermore, the tooling (Makefile, etc.) to build the RST files to HTML pages is also missing on fricas/fricas.github.io: FriCAS documentation.

If it would be kindly possible to reorganise the sources and provide the tooling, I could actually edit the sources and submit a PR on fricas/fricas.github.io: FriCAS documentation for your review. Alternatively, you could also point me to where to find these and I could reorganise everything myself in a PR. It it would be Ok, I want to (especially) improve the "install" and "examples" (with broken links, etc) sections a bit as a first step.

I feel that once FriCAS installed and going, "the book" is an amazing resource and ideally one needs nothing more ! :)

Best regards,

Aravindh Krishnamoorthy

My GitHub profile: aravindh-krishnamoorthy (Aravindh Krishnamoorthy) (github.com)

[Waldek Hebisch]

On Thu, Dec 28, 2023 at 05:53:50AM -0800, Aravindh Krishnamoorthy wrote:
> Dear Ralf,
>
> This is my first post on this group.
>
> I'm a FriCAS user since a while and recently introduced FriCAS to a few
> colleagues who are hackers (i.e. familiar with Mathematica, Python, Git,
> etc.). Unfortunately, the entry bar is still quite high. IMHO this is
> largely due to the incoherent and unmaintained documentation, especially
> the "install" and "examples" sections of the website. Sorry; I understand
> that this project is a community effort and everyone's doing their best.
> But, the documentation definitely needs some improvement.
>
> I wanted to submit a PR to fricas/fricas.github.io: FriCAS documentation

> <https://github.com/fricas/fricas.github.io> but noted that the actual

> sources are scattered across "_sources", the repository fricas/fricas-doc:
> Sources for documentation part of https://fricas.github.io

> <https://github.com/fricas/fricas-doc> and other repositories. Furthermore,

> the tooling (Makefile, etc.) to build the RST files to HTML pages is also
> missing on fricas/fricas.github.io: FriCAS documentation

> <https://github.com/fricas/fricas.github.io>.

I do not know what exactly is in <https://github.com/fricas/fricas.github.io>,
but my impression was that this is merely a storage place for generated
files. Concerning what is visible at <https://fricas.github.io/>,
AFAICS bulk of it is 'book.pdf' and API pages. Both are generated from
FriCAS sources and build infrastructure is in
'<https://github.com/fricas/fricas/>, more precisely in the 'src/doc'
subdirectory of the source tree.

From <https://fricas.github.io/install.html> subsection "Build
extra documentation (book and website)":

: The FriCAS home page can be built via
: cd $BUILD/src/doc
: make doc

I did not check but IIUC when this finishes succesfully the 'html'
subdirectory contains copy of the website. There are prerequisites
for documentaion build, they are given in the section that I mention.

There is a little subtlety in the above: <https://fricas.github.io/>
contains documentaion for FriCAS-1.3.9, while if you fetch current
sources from the trunk you will get documentation about trunk. In
particular API changed: few functions are gone, there are new
functions. If you build from current source most (hopefully all)
broken links will be fixed. But since website is supposed to
be about FriCAS-1.3.9, to fix it one needs to fetch 1.3.9 sources
and apply the same fix to 1.3.9, rebuild documentaion and then
upload to github.

> If it would be kindly possible to reorganise the sources and provide the
> tooling, I could actually edit the sources and submit a PR on fricas/fricas.github.io:

> FriCAS documentation <https://github.com/fricas/fricas.github.io> for your

> review. Alternatively, you could also point me to where to find these and I
> could reorganise everything myself in a PR. It it would be Ok, I want to
> (especially) improve the "install" and "examples" (with broken links, etc)
> sections a bit as a first step.

Hmm, "install" clearly failed, as you did not find information how
to rebuild documentation. The first step to contribute should be
for you to repeat documentation build following instructions from
the 'install.html' (plain text version is in the FriCAS source tree
as 'INSTALL'). Source for 'install.html' (and 'INSTALL') is in
'src/doc/sphinx/source/install.rst', 'INSTALL' is generated using
a script 'generate_INSTALL.sh', 'install.html' is created as part
of general documentation build.

BTW: You wrote "the website", but really there is no "the" here.
Most up to date information is at SourceForge, <https://fricas.sf.net/>,
but this is handful of pages for the rest linking to other sites.
Github pages usually are updated at release time.
<https://fricas.github.io/> contain API pages, but other pages
are less up to date than SourceForge or Github project pages:
on SourceForge I can update individual pages and there is only
handful of them so it is easy to keep them up to date.
<https://fricas.github.io/> requires build and some care to
avoid unwanted changes, so it is updated less frequently.
Well only Ralf updates <https://fricas.github.io/>, while
I change sources I did no update to the site itself, one
reason is that most changes should not go there (are about
future release), the second reason is that since process is
a bit involved I do not want to interfere with Ralf work.

--
Waldek Hebisch

[Ralf Hemmecke]

Hi Aravindh,

Sorry, but I am ill at the moment.

>> I wanted to submit a PR to fricas/fricas.github.io:

It make no sense to put a PR there, since this repo only holds the
generated HTML files to be shown at github.

> '<https://github.com/fricas/fricas/>, more precisely in the 'src/doc'

Exactly, this is where the documentation lies. The files for the website
are under src/doc/sphinx/source.

Can you wait a bit with your pull requests, I have something locally,
but did not have time to finish and publish. Sorry.

BTW, the repo fricas/fricas-doc is not used. I should perhaps remove it.
The documentation lives completely in fricas/fricas except the example
pages (some jfricas notebooks) that live in fricas/fricas-notebooks.

I'd be happy to discuss the documentation with you when I feel better.

Ralf

[Aravindh Krishnamoorthy]

Dear Waldek and Ralf,

Firstly, thank you very much for your quick replies.

> Sorry, but I am ill at the moment.

> [...]

> Can you wait a bit with your pull requests, I have something locally,

> but did not have time to finish and publish. Sorry.

> [...]

> I'd be happy to discuss the documentation with you when I feel better.

Ralf, wish you a speedy recovery! I will look forward to the discussion on the documentation. In the meantime, I will try to follow the instructions (exactly) from 'install.html' and ensure that they work, as suggested by Waldek.

> Hmm, "install" clearly failed, as you did not find information how
> to rebuild documentation. The first step to contribute should be
> for you to repeat documentation build following instructions from
> the 'install.html' (plain text version is in the FriCAS source tree
> as 'INSTALL'). Source for 'install.html' (and 'INSTALL') is in
> ' src/doc/sphinx/source/install.rst', 'INSTALL' is generated using
> a script 'generate_INSTALL.sh', 'install.html' is created as part
> of general documentation build.

Thank you very much for this and for the doc build instructions. This is the first time I installed FriCAS from the sources and I did, in fact, read this section. But, based on the GitHub commit timestamps, my first instinct was to suspect that the instructions are outdated and that the website is built from private sources. Please note that the '_sources' directory in the repo https://github.com/fricas/fricas.github.io does have updated (recent) files, incl. 'install.rst.txt', adding to the confusion.

> BTW: You wrote "the website", but really there is no "the" here.
> Most up to date information is at SourceForge, <https://fricas.sf.net/>

Thank you again for this info. In my (very) biased view, SF is "old world opensource" and GitHub is the "new world opensource;" so when a GitHub repo is available, I invariably (and in this case wrongly) assume that's the latest one.

I look forward to discussing with Ralf once he's well and assisting him with the documentation.

-- ark