libera/#commonlisp - IRC Chatlog
Search
7:43:00
beach
Here is a project for a relative newbie who wants to learn more about Common Lisp: Create a site that contains definitions of standard Common Lisp macros that are truly portable, i.e. where there is no implementation-specific machinery required, neither for the expander nor in the expansion.
7:44:25
beach
The license should be very general so that these macros can be used in most Common Lisp implementations.
7:46:32
beach
The macros should have good comments and good documentation, including documentation strings.
7:47:50
beach
The best way to establish these macros would be to look at the most common free Common Lisp implementations and then choose a general technique accordingly, while taking care not to violate any copyright.
7:54:30
beach
Not that anybody usually decides to work on any of the things I suggest (other than myself), but I think this is an easy one that could cut the collective maintenance burden of maintainers of Common Lisp implementations.
7:59:21
pjb
beach: that's about most of https://gitlab.com/bocl/bocl/-/blob/master/sources/lisp/macros.lisp#L310
7:59:57
pjb
beach: that said some important macros have to deal with environments, and cannot be completely independent from the implementation.
8:01:49
beach
Right. I specifically wanted to distinguish those macros that do not require any particular machinery.
8:03:22
beach
There are obviously several implementation of these macros in different Common Lisp implementations, but I wanted a separate repository for them, and documentation and such.
8:04:20
beach
And I was thinking that a relative newbie looking for a project could figure out what macros are truly portable, centralize them, write documentation strings and comments, etc.
8:16:48
splittist
beach: [not volunteering] So essentially nothing from Chapters 1-4 of the Spec; some from Chapter 5 (?); all of Chapter 6; some (?) of Chapter 7; Chapter 8 (defstruct); phoe's done Chapter 9 (conditions); nothing in Chapter 10; some of Chapter 11 (?); the handful of macros in Chapters 12-21; Chapter 22 (reader) is mainly the pretty printer (?); Chapter 23 (reader - with-standard-io-syntax) ; then Chapters 24 and 25 are pretty
8:21:45
beach
I think in SICL/Cleavir we just use the usual technique for preserving source information in macro expansions.
8:33:38
lisp123
Or should we keep them short. Issue with comments is that they may not be discoverable outside of the file
8:36:10
beach
lisp123: The documentation string is meant for clients and are mainly useful on protocol functions and classes. Comments are meant for the same people who read the code.
8:36:32
beach
lisp123: And the problem with documentation strings is that they are largely noise to the person reading the code.
8:36:39
lisp123
beach: Ah, so doc strings, I should explain INPUT & OUTPUT and comments I can do whatever is helpful?
8:37:39
beach
lisp123: So, ideally the documentation strings should be long-ish, but the problem with that is precisely the noise aspect.
8:38:18
lisp123
beach: i know what you mean, for lisp coders, one can read the code and understand exactly what its doing, doc strings are just repeating oneself in another (inexact) form for that purpose
8:38:20
beach
So I tend to use (SETF DOCUMENTATION) in a separate file so as to avoid the noise. But then there is the problem of keeping them synchronized instead.
8:39:59
lisp123
beach: thanks, that's going to be very helpful. Time to seperate out docstrings and only do them for exported functions :)
8:40:41
beach
lisp123: I tend to use #.(format nil "...") for documentation strings, so that I can use ~<newline> with the @ modifier, so that subsequent lines can be indented without changing the output of DOCUMENTATION.
8:45:33
beach
I guess one could either hide the documentation string in the definition, or provide a way to access the (separate) place where the documentation string is located, in a separate buffer.
8:50:39
splittist
(actually, that question doesn't seem to make sense - why deal with files at all?)
9:05:12
beach
moon-child: That's just my default choice. If you can convince me otherwise, I am all ears.
9:05:44
jackdaniel
it's simple. you have an ascii table printed on your desk an you edit the file with a hexeditor
9:06:58
beach
None other than that editing source code in the form of text still seems to be the most common way.
9:10:42
beach
I did attempt to design a "structure editor" at some point. The idea was to have a bunch of keystrokes valid in different contexts, so that the editing experience would resemble that of a text editor, but with fewer possibilities of making mistakes. It turned out to be too complicated though. Probably because I didn't find the right data structures for it.