On Fri, Dec 13, 2024 at 06:47:29PM +0000, Martin Baker wrote: > On 13/12/2024 16:37, Waldek Hebisch wrote: > > I wrote about dynamic "server-side" generated pages. I agree that > > javascript may be problematic, that is one reason to do dynamic > > part on server side: from client point of view this is the same > > as static pages. Simply, instead of pr-generating inpractically > > large number of pages sever may generate them on the fly. > > That looks ambitious to me but I don't know much about server software. > Would it run on Github or would it require use of a university server > somewhere?
For server-side generated pages you need ability to run sofware of your choice on the server machine. That excludes Github or more generally various "web hosting" offers, requireing running it locally on user machine or a "dedicated server", like 'fricas.org'. This does not exclude possibility of hosting pre-generated pages in Github, simply pages generated on the fly would be absent from Github site. > Something makes me uneasy about this, I'm just thinking back to the > issues I saw on this thread about the axiom-wiki. I thought that server > software was high maintenance due to all the things that can change such > as: 'new version of Debian', 'hard disk dying', and so on. > I am just worried about the FriCAS documentation disappearing off the > web every time there is a software glitch. 'axiom-wiki' has three releated problem: - it depends on LaTeX wiki software, which is unmaintained for many years, - via LaTeX wiki it depends on Zope which stores data as a binary blob which only Zope can read, - Zope rather frequently changes in incompatible ways. Due to above there would be substantial work to move to newer version on Zope and we are currently stuck with very old version. For some time it looked hard to upgrade system on the machine, as Zope depends on specific old version of Python, but this part is resolved now, I identified want we need and can install old Zope and old Python on a new system. Of course 'hard disk dying' may happen, but actually one disc dying is not a big trouble, one simply replaces the drive. Trouble was two discs failing in short interval (like two weeks) during holiday time, so there was nobody in place to quickly replace failed disc. And at core of trouble was faulty series of disc drives, similar failures affected other machines later (but discs were replaced quickly enough to avoid data loss). > Would it be possible to retain https://fricas.github.io/ for what it > does now and just link to the dynamic pages for things like: searching > function names or live execution of examples. Yes. > In practice I wonder how useful live execution of examples is? Its hard > enough/impossible to get people to write even minimal documentation and > this live execution would be a lot more work on top of that. So > realistically, is it likely to increase beyond the small number of > examples already in HyperDoc? Not so small if you count FriCAS book. Concerning usefulness, I think that this is useful, but I want to get other things working with HTML first, especially search. I mentioned live execution as a thing which more complicated that other things, at least when you want this working over internet. > > Well, I prefer to distinguish presentation form logic. IMO in logic > > aspect HyperDoc is reasonably modern, main "logic" drawback of current > > HyperDoc is that it gives unrestricted access to FriCAS, so it > > can not be directly exposed to internet (at least not without extra > > protection). I think that for API server use this can be fixed with > > resonable effort, so the FriCAS only presents API and nothing more. > > I don't understand this. What would it give access to? the source code? Source code access is just links, no trouble. Claryfing a bit, currenly HyperDoc implement large part of its functionality by sending commands to FRICASsys. Those commands can do essentially anything, basicaly can upload new code to FRICASsys and using system calls do anyting that Unix process with permissions of FRICASsys can do. That is OK if FRICASsys and cource of commands runs on the same machine (that is both run on user machine) with no access fromoutside. But this is security trouble, when we want access from internet. For this we need to restrict available commands to some allowed subset. API pages like current pages in Github pose no trouble, they are easy to recognize and validate. Search as done currently in HyperDoc is more tricky, as HyperDoc allows arbitrary expressions in type parameters. But AFAICS most general forms are rarely used and if we exclude most general cases the rest should be easy to filter. HyperDoc currently handles FriCAS book in C code (FRICASsys is only involved in live examples). 'api.spad' contains convertor from LaTeX susbset used in docstings to Restructured Text. IMO the approach will not scale up to more complex tasks, so I want a different convertor. I would like new convertor to handle FriCAS book. > > Concerning presentation, I want to offer HTML access, so that > > the same content that is currently available via HyperDoc can be > > accessed from web browser. If you look deeper, beyond "clunky" > > and "old" you should see that in current documentation there is page > > structure, links, etc, we just need to map the constructs to HTML. > > There are features that are harder to map, like "live" execution > > of examples. > > Yes, I really want to stress how important presentation is for new > users. Not just having HTML but having it nicely formatted for different > platforms like mobile. > > > Well, concerning API pages: negative part is that I do not see how > > we can get good search using current technology (that is Sphinx). > > Also, I find build time problematic. I would like to resolve those > > problems, and I think that direct generation of HTML can resolve > > both problems. So, my intent is to extend and improve API > > pages. > > > > I also wrote about HTML constructs. My low-level view of API > > pages is that there is bunch of templates (if order of 10) with > > slots that are filled with info. I consider generating info which > > goes into slots as main task (rest is basically a lot of string > > concatenations). Current 'api2.spad' uses very minimal templates, > > which are adequate to debug correctness of information, but are > > not intended as end product. And I wrote, work on generating > > info is not finished, there are docstrings to handle, conditions > > and sorting. However, there is also question of HTML templates. > > In principle we could just copy templates used by Sphinx. But > > this in unlikely to be optimal choice. That is reason for my > > HTML questions. End-user opinions about look of pages are > > important, but since 'api2.spad' is at early stage and look > > is quite different from what it can be my question was mostly > > to people developing web pages. That is Ralf, you, Bill Page, > > Arthur Ralfs (I do not know if they still read FriCAS list) > > and possibly others. > > So would these templates be automatically populated from the source code > and the '++' comments? It seems to me that there are already too many > sources of out-of-step documentation so I guess you want all the > official documentation to be derived from some common root? Yes, exactly. -- 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+unsubscr...@googlegroups.com. To view this discussion visit https://groups.google.com/d/msgid/fricas-devel/Z1y8if1YtkOPy_fu%40fricas.org.
