I am glad to hear that you are enthusiastic about improving the documentation. Tell me if there is anything specific I can help with.
As a first step, I can offer a general suggestion. Surely you have a family member or a friend who is digitally literate but not familiar with Common Lisp and FriCAS. Ask them to set up a FriCAS Jupyter notebook and watch. Will they even be able to find the installation guide? It is not linked to from the table of contents! This method is called «usability testing» and you can find more details, for example, in the book _About Face 3_, chapter 4. Overall, this problem calls for two items of documentation: a guide and an explanation. * The guide would be a list of steps that can be performed with minimal research. The three commands listed right now are clearly not enough. Whence do I get this `hsbcl-1.3.9.tar`? How do I check if all the steps succeeded — what should happen? At what point in the build process do I run these commands, in what folder? This is also where you can mention Quicklisp if it is helpful, or not mention Quicklisp if it is not helpful. Usability testing will help you figure out the best way. * The explanation would define all the terms and give links where appropriate. It would put everything in perspective. Maybe it would say that FriCAS is based on Common Lisp and it needs to be built with a specially prepared Common Lisp executable that has a web server baked in. You should also explain what a «FriCAS distribution area» is — I could not find it. Again, you can use ethnographic methods to figure out if the explanation is clear. You can read [Divio Documentation System](https://docs.divio.com/documentation-system/) for more and better suggestions on the topic of documentation. > > Annoyingly, HyperDoc pops up every time I restart my FriCAS Jupyter > > notebook. This is an annoyance that I wish I knew how to disable. > > That is easy. jFriCAS starts a new fricas for every jupyter notebook > that you open. You find here > > https://jfricas.readthedocs.io/en/latest/misc.html#fricas-start-options > > that you would have to look into fricaskernel.py. > > Read > > https://github.com/fricas/jfricas/blob/master/jfricas/fricaskernel.py#L496 > > and then do the respective changes in the fricaskernel.py that you have > installed. I, for example, have installed jfricas into a virtual > environment under $HOME/virtualenv/jfricas. So for me it is the file > lib/python3.12/site-packages/jfricas/fricaskernel.py > inside that directory. > > I usually run jfricas with > > pid = Popen(['gnome-terminal', '--title=jfricas', '--'] + > ['fricas','-nosman','-eval',prereq,'-eval',start]) > > That still pops up a gnome-terminal, but this terminal is connected to > the FriCAS session that underlies the jupyter notebook. So you could > even modify variables from outside of the jupyter notebook. Thank you for this detailed example. I read the page you linked to earlier today in the course of my research, but I was intimidated by the need to edit the source code so I gave up. I see now there are friendly comments in there — this is nice. * I am not sure about `nosman` since it seems to also disable graphs, and I do want graphs. * I think this is a situation that calls for a configuration file. I do not believe editing the source code should be the preferred way of configuration, at least for the following two reasons: - If `jfricas` is installed via a package manager, such a modification would be erased when it is updated. - Many people will find this task intimidating. How FriCAS and jFriCAS should be configured is of course an architectural decision that requires deep understanding of the code and the use cases that need to be handled, so I cannot be of much help here. If I may suggest something, I should say there should be one place where everything may be configured. Right now there are at least four places — build configuration, command line flags, Python source code and the start-up profile file. This complexity seems needless to me. -- 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 [email protected]. To view this discussion visit https://groups.google.com/d/msgid/fricas-devel/CAB-2Q0-z40UEg-mt0HNhfbTi93A90QECWrF9-PMm8kLnnWZzKg%40mail.gmail.com.
