freenode/#lisp - IRC Chatlog
Search
8:32:02
flip214
beach: Documentation _has_ some connections to the software (function names, argument names and types, return types, classes, ...) but the missing part is prose. I'm not sure that a CLOS protocol is the right way to go.
8:33:11
phoe
look at all the documentation written that uses all sorts of its own markup languages with manual or no xrefs and/or outdated examples that don't compile and such
8:33:20
flip214
I'd imagine letting the user choose his markup and use eg. pandoc to convert to something that can be merged with the details from the image.
8:34:15
beach
flip214: Maybe it is not clear what I mean. I mean definitions of classes such as paragraphs, words, titles, cross references, and functions such as formatting, etc.
8:34:54
fe[nl]ix
semantic data, like what to include in an index, what / where to x-ref, then there's the prose
8:35:03
flip214
pandoc already has an internal JSON format defined, that might be a good first guess https://pandoc.org/filters.html
8:36:18
flip214
I thought you meant (defmethod documentation ((type (eql :class)) (name (eql 'myclass)) (...)))
8:37:29
phoe
beach: CCLDoc does not document its protocols; it has an internal structure for documents/paragraphs and such and a way of reading these from sexp files.
8:37:42
flip214
fe[nl]ix: well, I had good results with doxygen, so why not define ";;*" as the starting tag of a parsable-comment block? (variable number of semicolons, of course)
8:38:16
flip214
beach: well, I/O is _exactly_ what the users (the people writing documentation) mostly care about!
8:39:20
phoe
flip214: that's why we have lots of the I/O and little of the overall cohesion that we want
8:39:41
fe[nl]ix
flip214: I don't want to embed documentation in my source files, that's precisely what I want to avoid
8:40:50
flip214
I'm using that as well... but being able to explain some configuration convention right at the point where it's implemented is very nice
8:42:46
fe[nl]ix
pandoc is also inadequate because it's just an engine for transforming between markup formats
8:42:54
beach
If we put documentation in source files, we need to either use plain text, which is inadequate, or we need to agree on a markup language, which, as I said, we can't.
8:42:56
phoe
flip214: ideally you'd be able to right-click that symbol and choose an option to view its documentation
8:45:02
phoe
and all of this infrastructure is absolutely required to avoid the curse of documentation written in plain text and/or yet another markdown derivative
8:45:03
fe[nl]ix
unless somebody takes initiative, I hope to write some sort of design doc in the next few months
8:45:42
beach
Since we probably need to save documentation to files (given the state of current operating systems), we could use some very simple format like what I use for ASTs in Cleavir: [<class-name> :initarg1 <value1> :initarg2 <value2>...].
8:47:15
flip214
phoe: beach: well, I think we don't need to agree on a markup format. Define a comment tagging mechanism and pass via an argument which format is in use, then use pandoc to convert to whatever representation your UI wants.
8:48:06
flip214
and even my non-lispy vim can fold comment sections away, so if it's in the source files it doesn't _have_ to get in the way.
8:49:16
beach
But I haven't had time to look at it at all, so I don't know whether he is on the right track.
9:55:08
contrapunctus
phoe, beach, flip214: do y'all need something like this? https://github.com/CommonDoc/scriba
9:56:54
jackdaniel
contrapunctus: the point is to have a "live" documentation in a program (in contrast to a source code), with ability to save/restore that documentation
9:57:36
jackdaniel
then you can add import/export functionalities, or even live markup parsers when writing the documentation
10:08:02
contrapunctus
Well lol "This library can be considered an implementation of Robert Strandh's suggestion for the creation of a library for representing documents [...]"
10:28:55
splittist
I think most document modelling goes too quickly from the abstract (tree) to the particular (italics, numbered list). There are useful layers that could fit in between.
12:48:02
beach
phoe: Heh, so it's good to see that someone is paying attention (referring to commondoc).
17:32:16
jackdaniel
by standard he meant something what is /expected/ to be implemented by common lisp vendors
17:54:53
_death
so, where's the spec? it's just a library that people use.. there are others like it.. and now it'll be two libraries in one
17:59:23
Bike
i also meant something that's more exacting about specifications than portability libraries usually are
18:00:01
Bike
something that's important with atomics because debugging problems related to them is really annoying.
18:01:29
aeth
debugging problems related to threads is really annoying, atomics are just unnecessary in single-threaded programs.
18:02:13
Bike
i meant atomics makes things even worse than normal multithreaded programs. I thought that was obvious.
18:02:31
_death
it seems the new interface will have a document associated with it, but it's in a very early state.. https://sionescu.github.io/bordeaux-threads/
18:04:00
Bike
that's pretty reasonable in light of how patchy things are across implementations per shinmera's tracker
18:06:44
Bike
yeah. i've thought some about what an actual standard would look like and it would at least require a fair bit of work on every implementation
18:08:40
fe[nl]ix
for example, some implementations support atomic ops for struct accessors, but only for boxed slots
18:09:22
Bike
and one of the few libraries i could find using atomics, lparallel, assumes reads are sequentially consistent, i believe
18:10:49
fe[nl]ix
the only implementation that has a documented and well-thought API for barriers seems to be Lispworks
18:28:24
jackdaniel
timeouts are not implemented (I have them working locally, but that needs cleanup I did not have time to apply lately). also, they are based on spinlocks for portability; I suppose using i.e pthreads unices would be better for both cpu and performance
18:28:57
jackdaniel
I want to also bring back green threads, so there is n-to-m mapping; but that's another story
18:39:26
fe[nl]ix
jackdaniel: once Linux gets support for usermode scheduling, I'd like to experiment with a simpler Lisp before adding that support to SBCL
18:42:44
p_l
fe[nl]ix: doesn't read to me as full MxN threading... more like another implementation of what was part of QNX RPC port or the code that is part of Android Binder
18:45:01
jackdaniel
fe[nl]ix: if you have questions regarding ecl (if you decide to experiment with it) please let me know
18:55:40
fe[nl]ix
it's technically still 1:1 but the process can determine its scheduling priorities and control switching
19:04:02
p_l
Binder did that combined with the RPC - this meant that when you call a "remote" service, you stay in the same scheduler time slice
19:36:26
Duuqnd
From usocket's page on common-lisp.net: "(IPv6 support is also in progress and already available for SBCL/CCL with version 0.6.3+)"
19:37:36
gendl
now i have to make sure i have that version and see how to use it. I'm not seeing an argument for ip version in usocket:socket-listen
19:45:21
gendl
yeah i'm not seeing anything about ipv6 in https://common-lisp.net/project/usocket/api-docs.shtml
19:57:39
gendl
if you simply specify an ipv6 host to socket-listen, it'll be a ipv6 socket. Or just use *wildcard-host* which will make it listen for ipv6 connections on ipv6 capable systems.
20:06:45
phoe
I remember being stung by usocket that making a socket on "localhost" opened a socket on ::1