This was one of the motivations behind JOD. Here's a quick snapshot of something I am working on right now. The dictionary tracks and displays appropriate "documentation" on demand. Of course you still have to do a little work - entering a brief statement of what a particular word is about.
The addon distribution does not include all these dictionaries but you can get most of them (nonwork) from https://github.com/bakerjd99/jacks require 'general/jod' NB. list available dictionaries od '' ┌─┬────┬─────┬──────┬───┬──────┬────┬─────┬────┬────┬───────┬─────┐ │1│docs│image│import│jod│joddev│junk│mwecc│play│smug│smugdev│utils│ └─┴────┴─────┴──────┴───┴──────┴────┴─────┴────┴────┴───────┴─────┘ NB. show currently open dictionary summaries did ~ 0 ┌─┬──────────────────────────────────────────────────────────┐ │1│┌─────┬──┬─────┬─────┬───────┬───────┬──────┬────────────┐│ │ ││ │--│Words│Tests│Groups*│Suites*│Macros│Path* ││ │ │├─────┼──┼─────┼─────┼───────┼───────┼──────┼────────────┤│ │ ││mwecc│rw│330 │9 │20 │0 │19 │/mwecc/utils││ │ │├─────┼──┼─────┼─────┼───────┼───────┼──────┼────────────┤│ │ ││utils│ro│331 │7 │17 │0 │9 │/utils ││ │ │└─────┴──┴─────┴─────┴───────┴───────┴──────┴────────────┘│ └─┴──────────────────────────────────────────────────────────┘ NB. list groups (modules) de grp '' APL385UnicodeTest CdmColumnXref CdmTester CountryWide CwfRegression CwfResearch FuzzyAlerts GridDemo ICD MathJaxDemo Outliers RecodeSchedZ UltimateLosses base64 boxopen bstats buildutils dbi dbicreate dbimodelsample dbisqlite dbitester dewhitejscript dllutils earthdistances htmthorn ijfFrsf jdemo2 odbcREF remdots rwtabd socketsREF sunmoon trig unicode wordformation xmlutils NB. brief summary of words in a group hg 'bstats' ┌────────┬──────────────────────────────────────────────────────┐ │antimode│finds the least frequently occurring item(s) in a list│ │dev │deviation about mean │ │dstat │descriptive statistics │ │freqdist│frequency distribution of numeric items │ │fuserows│opens and catenates boxed lists on the last axis │ │geomean │geometric mean of a list │ │harmean │harmonic mean │ │kurtosis│kurtosis │ │lsfit │coefficients of polynomial fitting data points │ │mean │mean value of a list │ │median │median value of a list │ │midpt │mid-point │ │mode2 │finds the most frequently occurring item(s) in a list │ │movgmean│moving geometric mean │ │movmean │moving mean │ │q1 │first quartile │ │q3 │third quartile │ │round │round y to nearest x (e.g. 1000 round 12345) │ │skewness│skewness │ │ssdev │sum of square deviations (2) │ │stddev │standard deviation (alternate spelling) │ │var │var │ └────────┴──────────────────────────────────────────────────────┘ On Tue, Jan 14, 2014 at 3:15 PM, Don Guinn <[email protected]> wrote: > So many names in the z locale. I wonder what that looks like to a newbe. > Take a name like splitstring. Got a pretty good clue from its name. Where > is it defined? Exactly how can one use it? Easy enough for someone familiar > with J to just look at its definition then play with it a little. Maybe go > find the script in which it is defined and look for comments. But a new > user would probably just give up and not use it. But if there were a > description of its usage somewhere it would e many times larger than the > definition. > > For one experienced with J such documentation is unneeded. But what about a > newbe? They are the ones who need a jump start so they don't become > frustrated. > > > On Tue, Jan 14, 2014 at 8:01 AM, Raul Miller <[email protected]> > wrote: > > > I have also struggled with documentation, and not only in the context > > of apl and/or j. > > > > I sometimes wonder, though, how important it really is. So much of the > > skill of computer programming comes through seeing the code through > > experimentation and seeing both the code and its variants in action. > > > > Quite often, I find that the code makes a lot more sense when I see > > what it is doing. (And, all too often, that winds up being "nothing > > useful" so then I wonder if there are other cases where it would be > > useful.) > > > > Anyways, writing documentation is a mentally and socially intensive > > task, and I have the utmost respect for people that can do it well. > > And good documentation gives valuable perspectives and insight into > > the underlying code. But... it's a struggle for me. > > > > Thanks, > > > > -- > > Raul > > > > On Tue, Jan 14, 2014 at 9:47 AM, Don Guinn <[email protected]> wrote: > > > It's always been a mystery to me why it is OK to spend several hours > (or > > > sometimes days) analyzing several pages of FORTRAN or C but when > reading > > a > > > few lines of APL or J which do the same thing I must grasp it in a few > > > minutes or I start feeling overwhelmed. But I have written similar > > > "run-ons". Why? Because I can set up test data and add a little at a > time > > > to a line or a few lines, executing it and looking at the results as I > > go. > > > I have to force myself to break that monster up into more readable > > chunks. > > > I can't do that in other languages as I have to compile or whatever, > So I > > > tend to write all the code then start debugging. > > > > > > Then comes documenting. I put a brief description of what it's for and > > > expected arguments. Then add references and why the code does what it > > does. > > > I try not to repeat describing what the code does. But then I end out > > with > > > comments many time larger than the code. That just seems weird! > > > > > > ---------------------------------------------------------------------- > > > For information about J forums see http://www.jsoftware.com/forums.htm > > ---------------------------------------------------------------------- > > For information about J forums see http://www.jsoftware.com/forums.htm > > > ---------------------------------------------------------------------- > For information about J forums see http://www.jsoftware.com/forums.htm > -- John D. Baker [email protected] ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
