I updated my baruch program for lisp today, to version 0.2 - baruch creates API documentation by writing docstrings into asciidoc files.
The main changes are:
- uses 'closer-mop', so is compatible with all the lisps that library works with
- adds a 'document-system' function, to pull out info from defsystem.
Guess the website!
> I asked some pianists [How to figure out what is "correct" fingering] and I've got 3 versions of answers ... followed by advice to try out and see what works
> I think of it like a dynamic programming type situation.
Imagine this as an xy-problem: "I need help trying to solve this dynamic programming problem ..." ... some time later ... "OK, what is your real problem?" "What is the correct fingering for this piano piece?"
#lisp's packages and systems are an odd pair, requiring and ignoring the other:
* packages are 'built-in' - they organise symbols
* systems are a library 'asdf' - they organise files
Typically (require :system-name) loads the system's files. Some of these files define packages containing symbols.
We access these symbols with (package-name:symbol-name ...).
Am I missing something:
* given a symbol name, which packages did it load?
* given a package name, which system loaded it?
Finally ... I completed the last docstring and reference link so my plotchart wrapper now has minimal documentation.
Like the proverbial camel, this project gradually took me over: two graphs became the whole library, then a second back end, then the API generator program, and even a re-theming of my website to make the documentation "pretty"! Sometimes, interesting code can grow out of the simplest of problems.
> doc = Asciidoctor.load_file 'min.adoc', safe: :unsafe
=> "Minimum Title"
=> "... <pre class=\"rouge highlight\"> ..."
Yeah, source highlighting applied!
I can now break-down large documents into pages in rake using the API, in place of my hacky html2pages program.
Jekyll (with one plug in), handles #asciidoc files, and the only newcomer difficulty was setting up the jekyll site (I had to delete the theme's _config.yml).
But amazingly, baruch-generated files appear automatically in the site menu!
Here's a demo, with explanation:
... experimenting over.
Today I posted an initial version of baruch, a program to create documentation for Common Lisp packages which uses #asciidoc format.
Write package-level and docstrings with optional asciidoc markup. Baruch then rewrites your package documentation and docstrings for all exported symbols into a standalone adoc file.
The project page is created by embedding baruch's self-documentation into my website (which is made from asciidoc files!):
About six months ago I wrote my own "static-site generator in a rakefile" when I realised all I wanted was some asciidoc files with a sidebar...
On reading the atdoc source, I learn that finding symbols and doc-strings is almost trivial ... that info just needs writing in asciidoc format.
So, that's what I'm experimenting with ...
I was looking for a #lisp documentation generator today. I prefer a two-tier system: API summary vs documentation.
For "real" documentation, I prefer to write in #asciidoc with many examples, but I don't want that cluttering up my source code. I do like to have "the latest" API pulled out from my code, along with the doc-strings.
I tried a few systems, but settled on atdoc. It seems to do what I want - a clean and simple listing of the public API of all my packages:
I have made a new release of ltk-plotchart, a lisp wrapper around tk's plotchart library.
This fixes a few internal features, and now supports both ltk and nodgui.
Thanks to @cage
for his comments and help, and also for making some changes to nodgui to help support the library.
Description and examples are at:
#conference call to the virtual Ninth Annual Conference on Advances in Cognitive Systems.
The overarching theme is to explain cognition in computational terms and to reproduce a broad range of intelligent behaviours in computational artifacts.
Paper submission deadline is August 20, 2021.
Conference: November 15-18, 2021
Sometimes people ... state exactly what you are feeling in words you could never find. I stumbled across this from Arthur Gleckler:
"As programmers, we are used to fast-moving projects, changing plans and informal customs. Getting software written at all is so hard that we have little patience for elaborate social protocol."
Actually, he's writing about an interesting scheme-related project - creating the scheme.org website.
Join the discussion: https://srfi-email.schemers.org/schemeorg/msg/15602174/
When I first learnt Lisp (in the 90s) I remember that using apply with too many arguments could fail, e.g.: (apply #'+ list-of-numbers) would fail if list-of-numbers was too large.
I was "worrying" about this limit yesterday. There's a lisp constant for its value: CALL-ARGUMENTS-LIMIT. The hyperspec says this must be no less than 50. I tried in sbcl:
I suppose this means I'm likely to run into other problems before this matters...
Tolkien's 'The Children of Húrin' was first published on 17th April 2007:
"But upon all whom you love my thought shall weigh as a cloud of Doom, and it shall bring them down into darkness and despair. Wherever they go, evil shall arise. Whenever they speak, their words shall bring ill counsel. Whatsoever they do shall turn against them. They shall die without hope, cursing both life and death." - Morgoth to Húrin.
A recent paper from our research group went online today. It talks about how simplification techniques can make the models generated in genetic programming smaller, and hence more understandable.
N. Javed and F. Gobet, "On-the-fly Simplification of Genetic Programming Models", in SAC '21: The 36th ACM/SIGAPP Symposium on Applied Computing, 2021.
#lisp rant on use-package. e.g. with ltk:
(grid (make-instance 'button ...) ...)
(ltk:grid (make-instance 'ltk:button ...) ...)
But I keep getting bitten. Today my code broke: ltk names in common-lisp-user were colliding with my (use-package :ltk) statement - deleting that left the ltk names unfindable... how did the names get loaded twice?
OK, it's me. I don't understand packages and defsystem, but ... save a future afternoon - follow the cookbook - 'bye "use".
uiop, part of #lisp asdf, has many useful functions.
`uiop:split-string` breaks a string into a list based on separators - `uiop:emptyp` flags empty strings, e.g. on splitting "1,, 2", which otherwise crash `read-from-string`:
(defun string-as-list (str)
(uiop:split-string str :separator ", "))))
* (string-as-list "1,, 2, a")
(1 2 a)
#conference call to the forty-first SGAI International Conference on Innovative Techniques and Applications of Artificial Intelligence. The scope of the conference comprises the whole range of AI technologies and application areas.
Paper/Poster Submission: Friday 2nd July 2021
Conference: December 14th-16th 2021, Cambridge, UK
#conference call to virtual MathPsych/ICCM 2021, the joint gathering of the 54th Annual Meeting of the Society for Mathematical Psychology and the
19th International Conference on Cognitive Modelling (ICCM)
MathPsych submissions close 15 Apr 21 (19:59 EDT)
ICCM submissions close 7 May 21 (19:59 EDT)
Conference 1st-12th July