> > > 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.
1) Basic comand pages, where it guides you to command and allows choice of parameters. We have only few such pages but in principle we could have much more (NAG version had several such pages for functions in NAG library) 2) Browser for operations and constructors. 3) Viewer for hyperdoc pages with option to execute examples. > > 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. Essential part of HyperDoc is linking between documentation and executable code. And ability to generate pages using arbitrary code. Details, that is if rendering is done by current HyperDoc or by say web browser is less important. But currently features are implemented in HyperDoc and alternative renderer(s) needs work. Also, HyperDoc was designed to work on computers of the past, so it uses limited resources. I must say that when I see Firefox using 300 Mb of memory I am starting to look for alternatives. > > 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 is final result. Arbitraly ugly source code can lead to nice formatted page. The point is if source format allows easy and natural expressing of what we need. reST does not look bad. But when I looked at description I saw no compeling reason to swith to reST. > > 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. Well, almost zero effort I can put the whole .ht file on a single line ("tr -d '\n'" will do it). The point is that we want to avoid overlong lines as they interfere with viewing and editing of .ht sources. \free and \bound will exceed 80 char limit with relatively small number of variables. > > 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. We have to agree to disagree here. In my practice I see tendency to use bigger and bigger formulas. It is nice to simplify things but theory says that there are object which are "irreducible" with respect to complexity. And we need computers precisely to handle objects that are to big for humans. > > 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? You could use webbrowser as alternative renderer instead of current HyperDoc program. IBM supported Saturn interface with moderate changes to code, so alternative renderers are within quite possible. Just somebody have to do it... > - 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. The point is that there is no need to replace: AFACS with modest effort current .htex files should work within browser. IIUC you want to go .htex -> .rst -> browser and envision .htex to .rst translation as one time operation. But there are several possible ways from .htex tp browser and it is feasible to do this on the fly. -- 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 [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.
