On Sunday 31 Jan 2010 16:59:14 Martin Rubey wrote: > Waldek Hebisch <hebi...@math.uni.wroc.pl> writes: > > And yes, it is inconvenient, but some folks here consider it the only > > right way to write programs... > > I don't find it inconvenient, but I understand well that Waldek does. > On the other hand, I find it very inconvenient to look for documentation > outside of the source file, which Waldek seems to prefer (see > fricas/doc/sttaylor.txt).
I think I'm with Waldek on this, I find this way of mixing in documentation very inconvenient, it may be useful to read the level of detail in sttaylor.txt once but I don't think I would want to wade though that, every time I wanted to find a piece of code once I understood the program. I found Arthur Ralfs documentation in the mathml pamphlet extremely useful and I could not have written my html formatter without it. But a lot of the documentation in the pamphlet is not specific to mathml, it belongs somewhere where any potential writer of a formatter will see it. The temptation is to duplicate this information into all the formatters where some copies will get updated and others won't. The end result will be more quantity but less quality of documentation. I find this is made worse because in SPAD the declarations and definitions are split up. So where do the explanations of the functions go, with the declaration or definition? Or is it duplicated? Or do I have to jump between them, over pages of detailed documentation, to find an explanation of the function or parameter? My solution would be to have a web of information, like hyperdoc, but for programmers. But this can't be done if the documentation is in pamphlet files. It seems to me that ordinary comments are good enough to help the programmer or maintainer work on the code which could contain links into the other types of information below. It seems to me that there are lots of types of documentation, like: User Guide ---------------- When to use How to use What functions are available. Programmers Guide ---------------------------- Overall architecture of the domain. Why a given category is used. How to build Known problems Mathematicians Guide ------------------------------- Text book stuff, definitions and so on An excerpt from a paper by an expert in the field Examples I've only looked at a few pamphlet files but they seem to have odd bits of all these types. If you are going to put this all in with the code then I think you would have to be very prescriptive about what goes where and I don't think that is likely to work in an open source environment. So I would have separate hyperlinked User Guide, Programmers Guide and Mathematicians Guide. I can see some problems with this, in that people might not feel such a sense of ownership with these documents as they might feel with pamphlet files. Anyway these are my first thoughts on the subject, I may grow to love pamphlet files but it seems unlikely at the moment. Martin Baker -- You received this message because you are subscribed to the Google Groups "FriCAS - computer algebra system" group. To post to this group, send email to fricas-de...@googlegroups.com. To unsubscribe from this group, send email to fricas-devel+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/fricas-devel?hl=en.
