On 9/21/07, Jason Grout <[EMAIL PROTECTED]> wrote: > Thanks for your replies! I'm now able to build the documentation and > get my changes into my version of the reference manual. > > As for reference material, I consider the reference manual the > comprehensive unabridged dictionary of SAGE. You know, something you > could curl up on a couch with on a rainy day :). I'd love to see it > expand to twice its size if the documentation is there.
Same here. > Also, an observation: > > I updated the reference tex files by doing: > > cd /sage/devel/doc/ref/ > ./update > cd .. > make pdf > > However, it claimed that there was nothing to be done, since everything > was up to date. I had to make clobber before it would build the > documentation again. > > Is there a way to have the ./update command touch a file which was then > a dependency for the make pdf/html/etc commands? That way, running > ./update would force make to rerun the pdf/html/etc generation. > > I'll open up a trac ticket. If this suggestion is a bad idea, feel free > to close the ticket. The main reason for ./build_pdf or ./build_dvi was that I couldn't figure out how to do exactly what you suggest above reliably. If somebody can figure it out, that would be appreciated. Incidentally, the whole sage documentation structure started from the Python documentation (probably Python 2.4), which I just motivated to be the Sage manuals instead. I had experimented a lot with automated tools like epydoc, etc., and found that they break a lot on the incredibly complicated Sage library, they don't play well with Cython code (which is nearly 1/3rd of Sage?), and and they just don't feel as well organized and readable as something that a person has to spend time putting together. The current documentation -- though not comprehensive -- tends to only have things in it that are "reasonably usable and stable", so the stuff that epydoc would pick up that is really a mess isn't there. That said, *pydoc has probably improved a lot in the last 2 years (since I last used it), and it would be good to have some 100% complete autogenerated variant of the reference manual in addition to the current more manually organized one. William --~--~---------~--~----~------------~-------~--~----~ To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-devel URLs: http://sage.scipy.org/sage/ and http://modular.math.washington.edu/sage/ -~----------~----~----~----~------~----~------~--~---
