Proposed change to Language Reference

#1

I propose to remove all the platform-specific information from the uLisp Language reference page:

Language reference

This would remove the tables of pin numbers for operators such as with-spi, and tables of keyword options for functions such as analogreference.

The problem is that it’s difficult keeping all of these up to date as I add support for more platforms to uLisp; in fact there are already many omissions in the tables that are there. These tables also make the Language Reference significantly longer.

I would move the information to the individual pages about each platform, such as BBC Micro:bit.

Does anyone see a downside to this, or have any alternative suggestions?

#2

I would say, it depends whether you value “length” (brevity) over “locality”. The way it is now, it allows you quick board comparisons as a “side-effect”, and you know “that is the only document you need”. Depends in the end on your own preference, of course. But the deeper issue here is: how many divergences are you even willing to tolerate?

#3

I take your point that it’s nice only having to refer to one document…

I’m not quite sure what you mean – can you elaborate?

#4

I mean, David, while the HARDWARE may offer possibilities, do you wish to explore all of them in the SOFTWARE? It may make sense to ignore certain “unusual” things, as we are bound to see fancier and fancier boards. E.g., you now offer assembler for a few boards — but will you continue doing that for further architectures? My idea is simply, you start to burden yourself with a lot of “parallel branches”. Just a feeling, you, of course, know this better.

#5

A consistent link such as “Platform / Board Specific Information” or similar as suggested is a great idea, as it would improve both the clarity and brevity of the language refgerence itself. Additionally potential contributors who use or advocate specific platforms could prepare such updates (in the style you specify) for inclusion. Being able to see all the platform specific details in a single document would also be handy for porting software. I am currently moving my new commercial projects from ATMEL based micros to Expressif and ARM based boards and the pertinent data for each is all over the place (uLisp & C++). Also anything that makes maintenance and updates (and thus the life & length of the project) easier is generally a good idea.