If you are interested in the current status, see the 'docs' topic branch.
You will see there some work products, particularly a marked up copy of the old manual, with my thoughts about what needs to be done, and a ledger of exported symbols, which should be documented in the manual.
Comments and suggestions welcomed. Patches also welcomed, but for that perhaps it's best you contact me. I'd be happy to cede parts of the manual to others.
Best, r
Dear Robert,
On Sat, Apr 5, 2014 at 11:31 PM, Robert P. Goldman rpgoldman@sift.info wrote:
If you are interested in the current status, see the 'docs' topic branch.
You will see there some work products, particularly a marked up copy of the old manual, with my thoughts about what needs to be done, and a ledger of exported symbols, which should be documented in the manual.
Comments and suggestions welcomed. Patches also welcomed, but for that perhaps it's best you contact me. I'd be happy to cede parts of the manual to others.
Thanks a lot for this important documentation work.
If you want me to document some functions you're not sure you understand, please tell me which.
Should it be a release blocker, though? Lack of documentation for exported functions is not a regression.
PS: I'm slightly disappointed you felt more comfortable using perl rather than CL for those scripts. :-)
PPS: my ASDF3 paper was accepted at ELS 2014! https://github.com/fare/asdf3-2013/ I already improved the paper much from the feedback, but more feedback still welcome, especially for the extended version of the paper. Said extended version can also provide background information or copy/paste material for the manual; conversely, parts of the manual could be removed and replaced with references to the paper.
—♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org An apple every eight hours will keep three doctors away.
Faré wrote:
Dear Robert,
On Sat, Apr 5, 2014 at 11:31 PM, Robert P. Goldman rpgoldman@sift.info wrote:
If you are interested in the current status, see the 'docs' topic branch.
You will see there some work products, particularly a marked up copy of the old manual, with my thoughts about what needs to be done, and a ledger of exported symbols, which should be documented in the manual.
Comments and suggestions welcomed. Patches also welcomed, but for that perhaps it's best you contact me. I'd be happy to cede parts of the manual to others.
Thanks a lot for this important documentation work.
If you want me to document some functions you're not sure you understand, please tell me which.
Should it be a release blocker, though? Lack of documentation for exported functions is not a regression.
I will do some triage on the changes needed so that it does not hold up the release excessively. I expect to get the manual to a "good enough for release" state before all of the exported symbols are documented, so I believe we are on the same page.
PS: I'm slightly disappointed you felt more comfortable using perl rather than CL for those scripts. :-)
I thought you might be! I know you think that CL should be an acceptable scripting language. Why did I still use perl? I offer these reflections in the hopes that they will inspire clever new solutions...
1. Paradoxically, AFAICT perl seems to provide a more REPL-like experience when scripting than does CL. It's so much easier to tweak the perl script, then re-run it. The CL alternative must be wrapped in a lot of scaffolding to make it runnable from the command-line -- that is, command line use seems radically different from in-REPL-use -- so it doesn't seem obvious to me how to quickly modify a CL script. I suppose one could run in the repl and then package for command-line use, but that is two steps instead of one.
2. While software purists no doubt deplore them, the implicit variables that perl offers provide significant terseness in writing filters that CL simply does not equal.
(iter (for x = (read-line str nil nil)) (while x) ...)
is a lot more typing than
while (<STR>) { ...}
3. Regexps: In perl regexps are in the language. In CL not only must we load a special library (a small nuisance), but the regexps are strings that are not in the language. This adds much unpleasant verboseness and quoting.
4. The relationship between the CL REPL environment and the standard unix notions of current working directory is annoyingly complex, since the notion of *default-pathname-defaults* sits in the middle. Also, it's a lot easier to use $FindBin::RealBin . "/foo/" than it is to use something like (or *compile-file-pathname* *load-truename*) and MERGE-PATHNAMES. *AND* there's the fraught issue of working that together with incremental compilation in the REPL.
I'm waiting for a lot more terseness before I give up using perl for line-based text file processing.
PPS: my ASDF3 paper was accepted at ELS 2014! https://github.com/fare/asdf3-2013/ I already improved the paper much from the feedback, but more feedback still welcome, especially for the extended version of the paper. Said extended version can also provide background information or copy/paste material for the manual; conversely, parts of the manual could be removed and replaced with references to the paper.
I hope to get a chance to look this over RSN (please lmk what is the deadline for comments before you have to have final copy in to ELS). But getting a good enough ASDF manual for release must be my first priority.
best, r
Should it be a release blocker, though? Lack of documentation for exported functions is not a regression.
I will do some triage on the changes needed so that it does not hold up the release excessively. I expect to get the manual to a "good enough for release" state before all of the exported symbols are documented, so I believe we are on the same page.
Good. If there are specific release-blockers I can help with, send them my way.
PS: I'm slightly disappointed you felt more comfortable using perl rather than CL for those scripts. :-)
I thought you might be! I know you think that CL should be an acceptable scripting language. Why did I still use perl? I offer these reflections in the hopes that they will inspire clever new solutions...
- Paradoxically, AFAICT perl seems to provide a more REPL-like
experience when scripting than does CL. It's so much easier to tweak the perl script, then re-run it. The CL alternative must be wrapped in a lot of scaffolding to make it runnable from the command-line -- that is, command line use seems radically different from in-REPL-use -- so it doesn't seem obvious to me how to quickly modify a CL script. I suppose one could run in the repl and then package for command-line use, but that is two steps instead of one.
I've tried to address that with cl-launch 4. I'm interested in specific issues, and hopefully, further changes to cl-launch can address them.
cl '(+ 1 1)'
#!/usr/bin/cl -i ccl -sp inferior-shell -E main (defun main (&rest argv) ...)
Packaging into a command what you debug at the SLIME REPL has never been easier.
- While software purists no doubt deplore them, the implicit variables
that perl offers provide significant terseness in writing filters that CL simply does not equal.
(iter (for x = (read-line str nil nil)) (while x) ...)
is a lot more typing than
while (<STR>) { ...}
Sure, but (dolist (x (uiop:slurp-file-lines str)) ...) isn't too bad.
- Regexps: In perl regexps are in the language. In CL not only must
we load a special library (a small nuisance), but the regexps are strings that are not in the language. This adds much unpleasant verboseness and quoting.
That's a good point, but fixable with a bit of readtable hacking, and should require a small finite amount of tools hacking to be fully recognized (still not there yet, though).
I think though that optima.ppcre is a much nicer interface to regex than perl offers, even with double quoting. I admit I also learned to quote characters with [.] rather than \.
- The relationship between the CL REPL environment and the standard
unix notions of current working directory is annoyingly complex, since the notion of *default-pathname-defaults* sits in the middle. Also, it's a lot easier to use $FindBin::RealBin . "/foo/" than it is to use something like (or *compile-file-pathname* *load-truename*) and MERGE-PATHNAMES. *AND* there's the fraught issue of working that together with incremental compilation in the REPL.
(uiop:current-lisp-file-pathname), (uiop:argv0) merge-pathnames is evil, but (uiop:subpathname ...) is good.
I'm waiting for a lot more terseness before I give up using perl for line-based text file processing.
I readily admit my CL scripts are less terse than Perl or shell, but so much more readable. And after a few hundreds of lines of code, so much better factored and so much easier to maintain, especially when I have to come back to them months later.
Also, there are a few informal patterns I use, such as computing an "environment" with many variables deduced from user specification, and passing it to functions as a keyword argument plist.
PPS: my ASDF3 paper was accepted at ELS 2014! https://github.com/fare/asdf3-2013/ I already improved the paper much from the feedback, but more feedback still welcome, especially for the extended version of the paper. Said extended version can also provide background information or copy/paste material for the manual; conversely, parts of the manual could be removed and replaced with references to the paper.
I hope to get a chance to look this over RSN (please lmk what is the deadline for comments before you have to have final copy in to ELS). But getting a good enough ASDF manual for release must be my first priority.
The date for final papers is April 21.
It would be really sweet if we could release before then, so the final version of the paper could describe a released version of the code.
—♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org |/ ____ |/ ~@-/ oO -@~ /_( __/ )_\ __U_/
-
Faré -
Robert P. Goldman