[Asdf-devel] Chipping away at the manual

[Faré]

>> 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...
>
> 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.
>
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.


> 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>) { ...}
>
Sure, but
(dolist (x (uiop:slurp-file-lines str)) ...) isn't too bad.

> 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.
>
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 \\.

> 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.
>
(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_/