> Hyperdoc program may be obsolte, but it works resonably well and we > have nothing that works better.
Waldek, you know that I am no big fan of HyperDoc anymore. In fact, I'm not using it. Can we, maybe, make it more concrete of what hyperdoc can do and where there is already a better alternative. > And AFAICS competition have shiny stuff that really is not better > (and frequently worse) than Hyperdoc. What competitors do you mean? Would be good to compare the current status with some vision of where we might want to go. > More important, we need a documentation format. .tex format allows > including actial FriCAS output of examples and has math support. It > is based on widely used system, that is LaTeX. I do not think that > there is better format around -- there are formats easier for > machine processing but really not suitable for writing by hand > (various *ML variants) and there are simple formats which IIUC lack > features. I'm certainly no expert in formats, and agree that LaTeX is a nice format, but I must say that I am no longer of the opinion that LaTeX is the best format for documentation. LaTeX is a format for printed documents. We should rather choose a format that allows to translate to HTML and LaTeX equally well. I'm actually quite certain, that reStructruredText is a nice format for FriCAS. Look at http://fricas.github.io/api, that uses reST and Sphinx (http://www.sphinx-doc.org). In fact, sphinx allows to include LaTeX formulas that also appear as LaTeX in the output (inside .html pages) and are then rendered via MathJax. I think that is a very reasonable approach. Furthermore, if we agree to let the ++ docstrings be in reStructuredText, it would be easy enough to be readable as plain text and rich enough to produce nice HTML pages (or even print it). I think, if you really want to keep HyperDoc, then we should be able to write a converter to the .ht format. (But actually, I would see no reason to put energy into HyperDoc.) > Not, both requirements to put things on a single line and limits on > size of expressing should be obsolete. Yes, I agree. But still I rather think we should be economical with our resources. Writing \free and \bound on the same line is (more or less) zero effort. Writing a program that gets all weird cases correct, is not. > Sometimes minimal example have to be big and both of the above are > problematic then. No, I don't really agree. I the reader has to parse tons of output, then it's not an appropriate example. We should make efforts to show only that part of a big expression that may be needed to understand what is going on. > Note that original authors developed texbreaker program. OK. But we cannot have both, LaTeX and texbreaker. And also texbreaker is not perfect and will sooner or later run into cases that it doesn't treat well. Who then is going to fix that? I'm for LaTeX, texbreaker does not work well with LaTeX, nobody maintains texbreaker, thus, texbreaker is dead (at least for me). Let me try to summarize. - The FriCAS book exists at http://fricas.github.io/book.pdf and is there probably nicer to read than inside hyperdoc. - The API is at http://fricas.github.io/api and probably also easier to read and to navigate than in HyperDoc. - HyperDoc has an Examples section. + That is already in the FriCAS book. - HyperDoc can find the place where a function is installed. + I would rather like to be able to ask for that information from within a session. Is this already possible? How? - HyperDoc allows to execute examples by entering parameters into fields. + Wouldn't that also be doable from within a webbrowser with HTML and a bit of JavaScript to call the local FriCAS? - HyperDoc lists the )commands. + Shouldn't be a big problem to translate that into reStructured text so that I can have it also at http://fricas.github.io . But I am not willing to sync .ht and .rst. If .rst starts to exist the other must go away. - The "Glossary" is only in HyperDoc + Relatively easy to translate to .rst. - The "Topics" entry in HyperDoc I cannot find anywhere else. Did I forget something? If we could integrate the Jupyter notebook interface at least as a supported GUI for FriCAS, then we could more easily provide example notebooks. In short, replace HyperDoc but a true Browser. Ralf -- 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 post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/fricas-devel. For more options, visit https://groups.google.com/d/optout.
