On Sun, Dec 08, 2024 at 11:06:48AM +0000, Martin Baker wrote: > I haven't been following this thread too carefully so ignore this if > I've gone off at a tangent. > I think you are discussing requirements for HTML documentation so here > are my requirements: > > I would like it to work reliably on any browser and any device (PC, > mobile, etc.) even when browsers change. For me static web pages are a > safer bet in this regard and would require a lot less maintenance when > things change than say javascript.
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. > I would like to look at FriCAS as a toolkit and I would like the > documentation to give me an up-to-date overview of all the mathematical > structures supported and then to be able to drill down to the details. > > I think its important that the documentation looks modern and supports > the conventions people expect and not a clunky old interface like > 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. 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. > I guess that's not important to the people on this list but I > think it will be frightening away new users. > > Of all the fragmented documentation for FriCAS I use > https://fricas.github.io/ as it best meets my requirements. I get the > impression that Waldek is very negative about this documentation, I > think that's a pity as I would like to see it extended and the other > documentation merged into it. 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. -- 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/Z1xivMGI0bvq5ZzJ%40fricas.org.
