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? 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. 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. 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?
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?
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? Martin -- 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/9eebea2e-5477-4b9a-9004-fe1426fee95c%40martinb.com.
