Jori Mäntysalo wrote: > OK. I'll close this path, as it seems that my view belongs to > minority.
I for one agree with you. More precisely, I do find the sage source code easy to navigate, making it easy to learn about Sage's capabilities *if* you know how to grep through it and make sense of what you see. I also find the tutorials pretty good. But the reference manual is IMO close to useless, if not misleading[#], and I'm far from convinced by the usual answer to use tab completion as a substitute. Let me use the occasion to advertise another ticket aiming to make the situation a little bit better: http://trac.sagemath.org/ticket/19058 And while I'm at it, some other half-baked thoughts (on which I have little time to work, unfortunately): - A long time ago, there was a discussion of moving the documentation of each function to a separate page in the reference manual. People liked the idea, and someone (Minh Van Nguyen?) made a prototype implementation, but it was never merged. This may be worth reviving. - Making class and method descriptions foldable in the HTML would probably help already. - Variant: group all methods called "foo" on a single page, or more realistically on a small number of pages, arranged using the class hierarchies and/or information from the category framework. This would probably require quite a bit of experimenting to get right! - The docbuilder should be aware of the main "special"/fundamental classes and methods in Sage and how they relate to each other. For example, Parents could link to their Element classes and categories, the docstrings of _add_, _mul_ and friends could be extracted to generate a section on arithmetic operations in an Element's documentation, and so on. [#] Try searching for "gcd" or "derivative" using the search box at http://doc.sagemath.org/html/en/reference/index.html, or try locating the documentation of rational functions... -- Marc -- You received this message because you are subscribed to the Google Groups "sage-devel" 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 http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
