Menu
▾
▴
#14 need documentation for modules, internal help
the documentation for reduce is lacking in the modules area. There needs to be examples and formal syntax given.
internal help needs to be documented too.
I can't even figure out how to use any internal help if there is any because it's not in the index.html help file. I noticed a lot of tex files so I am thinking the help is buried in those files, inaccessable to me... but no instructions or examples as to how to get at them. windows machines do not come with a TeX reader.
There is documentation on an external web site for redlog, but I have to download that. The documentation really should be all in one place if possible, and [installed as] part of the package.
PDF files are usable, I can switch back and forth between Reduce and Adobe Reader without taking up the Reduce screen, and I can search for what I need, and (hopefully) go to a bookmarked section in the navigation that I am interested in. Built-in help is also usable - it is quick.
Both are advantageous, however, internal help needs to be documented with external documentation for it to work, because everybody does internal help differently.
Ha Ha Ha!!!! One thing that Tony Hearn explained to me many many years ago is that groups in universities get credit and hence even possibly funding for the code they write, but preparing user manuals and careful documentation does not lead to any brownie points or tenure/promotion prospects, so keeping Reduce documentation up to date and up to scratch has been a struggle ALWAYS. Furthermore the version at present on sourceforge is essentially as it was when Reduce 3.8 was released a while ago. In the run up to that there had been a burst of activity (still imperfect).
The model wrt packages is that a package contributor gets their stuff in a subdirectory of "packages" and the *.red files are their source code and <packagename>.tex might be the documentation. Contributors have varied in style and how detailed their writeup is, but now things are open source we encourage ANYBODY to read and understand the code and submit updated or extra documentation. In the doc and util directories there are ill-explained scripts etc that at one stage people like me used to convert all the latex first into the pdf file that is still called r38.pdf (look in util) and sl.pdf (look in misc - it is the ancient "Standard Lisp Report" and is NOT a full reflection of current reality). They also make a bunch of .html files that the CSL (but note that the PSL version may differ) links to from its "help" menu item.
So there are several levels of issue to unpick here:
(1) The base *.tex files are uneven in style and quality, and may not be up to date. With different packages having been originally written by different people (some no longer available to help) this needs a few keen volunteers to work on!
(2) The scripts that turn these into .pdf and .html are not worked up into a state where they are cleanly explained and easy for anybody to work on. They have to date been used really just by the last distributor who needed to run them when 3.8 was released. When there are loads of new source files for them to be used on I guess I can help make them run again. It does not feel urgent until there is enough fresh raw text!
(2a) somebody better at html than me might have "more modern" ideas about the character of the html that the help files should be mapped onto...
(3) The meta-documentation of what the help system and manual are and can do is also sketchy. With luck this posting will help a bit on that.
On Windows I use miktex or the version of tex/latex that comes with cygwin to process .tex filles into .pdf. Those do not cost me anything and are not too hard to install.
One final point - redlog was in a huge state of explosive development when reduce 3.8 was released, and work on it has continued in an especially jolly way since. That makes it the clearest cut case of something where the documentation is not fully in the main Reduce tree and binaries. I have not looked at what happens if one tries to run the "make documentation" or"make help" scripts now but I would bet that many changes would be needed to accommodate both extra files in the redlog part of the tree and the fact that that packages has its own sub-sub directories within packages.
Arthur
Modules documentation added to manual