freenode/#lisp - IRC Chatlog
Search
7:47:23
beach
McParen: I don't know the answer to your question, but it is a bit strange to want to document a slot.
7:48:12
beach
McParen: Slots are implementation details, so the only person interested in the role of a slot would be the person reading the code, and then a comment is the appropriate way to describe what the slot is for.
7:56:34
beach
Just having a lambda list that you determined yourself, as opposed to OBJECT is worth it.
7:57:16
beach
Well, you may want to use that one anyway, since the documentation is not meant for the same category of people who read the code.
7:57:31
flip214
beach: ah, thanks. that reminds me - I've got a patch in the pipeline so that in sbcl the accessors use the class name instead of INSTANCE.
7:58:24
McParen
beach: What would be the appropriate place to document functionality for the users of a library?
7:59:09
beach
McParen: Users/clients should not know about slots. For such a person, a class should be defined by its initargs and its accessors.
8:00:28
beach
Quickdocs is an aberration. Documentation can not be generated from documentation strings.
8:01:25
flip214
beach: I guess we need something like doxygen, to parse documentation from comments.
8:01:31
fe[nl]ix
beach: I'd be extremely grateful if you could point me to an actual documentation system
8:01:46
beach
It is not added value if a user starts using internal features that happened to be automatically documented, but that may disappear in the future.
8:02:24
beach
flip214: Like I said, comments are meant for the maintainer and documentation strings for the user/client.
8:04:00
phoe
anything that is not based on docstrings or comments is the problem that fe[nl]ix and beach are discussing at the moment.
8:04:27
fe[nl]ix
my current effort: https://sionescu.github.io/bordeaux-threads/threads/make-thread/
8:05:51
beach
Yeah, me neither. When I emulated the Common Lisp HyperSpec look for the MOP, I got a lot of crap for it.
8:07:58
fe[nl]ix
in a way it's funny that Texinfo can do all that, but the output is atrociously bad
8:09:27
Duuqnd
I think Document Examiner had a printing function though so you could probably print it with a virtual printer and get a PDF
8:09:36
beach
As I have often said, any markup language is bound to fail to get consensus, simply because there are so many of them that each one is supported by only a small minority of developers.
8:10:27
beach
That is why I want to see a documentation system based on CLOS protocols that determine what operations are possible, something that all markup systems seem to fail to provide.
8:11:42
fe[nl]ix
if you build a system that gives users the ability to organize in chapters, with cross-refs, indexes, etc...
8:12:27
jdz
beach: I've been intending to look at https://shirakumo.github.io/cl-markless/ one of these days, it seems to be at least halfway in the direction you describe.
8:13:06
phoe
http://www.bitsavers.org/pdf/symbolics/software/genera_8/User_s_Guide_to_Symbolics_Concordia_Book_Design.pdf
8:13:29
flip214
phoe: not the number of bytes is important, but to keep the changes minimal so that it's easier to see the real changes. Like whitespace cleanups should be a separate patch.
8:16:51
beach
Oh, wow, "Markless", yet another markup language. I wonder how many are created per time unit?
8:17:46
beach
I bet the selling point is that you can then generate output in the form of markup for pretty much all previously existing markup languages.
8:18:57
phoe
well, as long as we write documentation in text editors instead of graphical ones we will be forced to reinvent Markdown, poorly
8:19:22
flip214
well, pandoc already can convert quite a set of markups into one another - and into word, LaTeX (and therefore PDF), HTML, DocBook, ...
8:19:33
pve
perhaps related: org-mode with org-babel can be set up to produce nice looking pdfs (through LaTeX) with syntax highlighted lisp code snippets
8:19:33
phoe
and by a text editor is something that merely edits text files instead of understanding them - which in turn is required for xrefs and such
8:19:51
beach
phoe: Yes, well, one possibility for a documentation system based on CLOS protocols would be to provide a specialized editor for it.
8:21:50
beach
Anyway, when I see this kind of proliferation of markup languages and testing frameworks, I immediately think there is something fundamentally wrong with the very concept.
8:24:05
phoe
fe[nl]ix: I guess that I personally do have high expectations after playing a bit with OpenGenera
8:24:53
beach
I should look into the state of "London" and maybe give jackdaniel some remarks on it.
8:24:56
Duuqnd
I mean, I *could* grab the time machine and stop Symbolics from going under, which would solve the problem...
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