freenode/#clim - IRC Chatlog
Search
4:19:51
nyef
If we have a full manual hyperlinked from our editor, is there still a point to docstrings?
4:21:23
beach
It is probably for that reason that I tend to avoid writing docstrings, and instead I write real documentation.
4:21:42
nyef
And the flipside question: User code often won't *have* a manual set up the same way, if at all. What needs to happen there?
4:24:06
beach
I would like a separate documentation system living in the image, but it would be based on representing documentation as objects respecting a particular protocol.
4:25:53
nyef
Yes, but that's somewhat orthogonal to the issue here, which is docstrings (which are mandated to a certain extent by the CL spec) and what to do about them.
4:28:23
beach
I see nothing wrong with having docstrings in addition to real documentation, other than the additional work.
4:30:39
nyef
I don't see that there's anything wrong with having docstrings as well as real documentation, but I don't see that there's much *point* to doing so.
4:31:12
nyef
Unless the docstrings are significantly easier to access than the "real documentation", they will be of marginal utility at best.
4:32:03
nyef
We have some evidence as to how people write documentation, though: Not at all, if they can get away with it.
4:35:16
beach
They often can't be shared between implementations, because, in my opinion, they should specify what the Common Lisp HyperSpec leaves unspecified, and that depends on the implementation.
4:37:01
nyef
And ISTM that about the only times we see a docstring are while editing the relevant section of code or in the output from DESCRIBE.
4:39:06
nyef
... Or when someone's taken the cheapass approach to documentation and done something to extract all of the docstrings from their program and called it a "manual".
4:39:59
beach
hooman: The Common Lisp HyperSpec leaves a lot of things unspecified, and the very purpose of a docstring is to explain what the function or whatever really does in that particular implementation.
4:40:40
nyef
But, again, *user code* often doesn't have any documentation beyond the docstrings, if at all.
4:41:44
beach
The other reason I want a separate system is that I would like for docstrings to be possible to change to other languages.
4:42:10
beach
When I still taught Common Lisp, it was striking how hard it was for my students to understand the English documentation.
4:42:26
hooman
i've converted all my elisp to literate programming, sort of, with org-mode, but it is a bit verbose.
4:42:43
beach
I can only imagine how hard it would be for (say) Chinese or Vietnamese students if it is this hard for French students.
4:43:06
beach
hooman: That's a very different kind of documentation, meant for the maintainer rather than the user.
4:43:12
hooman
CL docs are worlds away from other stuff. haskell was too, at first. prolog and erlang kinda. ML and ocaml a bit... everything else is the same.
4:44:11
beach
That's part of my problem with docstrings mixed with code. They are noise to the maintainer reading the code. That is why I prefer (SETF DOCUMENTATION) in a separate file.
4:44:39
nyef
Note that an implementation of CL:DOCUMENTATION that simply returned NIL for all inputs would be conforming.
4:44:55
hooman
beach, i am a bit of both in my situation. in haskell literate programming, everything is doc text - except lines that start with '>' iirc. with lisp it is interesting that the first char could only really either be ; or ( or # . i wonder how simple it would be to have emacs parse everything else as doc text for lisp.
4:45:35
dmiles
is it my immagination or was it common for docstrings in function to be using #| |# ?
4:45:53
hooman
not documenting inspires me to inject more clarity and simplicity and meaning and beauty into my code
4:46:02
nyef
Hrm... What if an editor had a pane which was always open to the manual page for the function or variable being defined closest to the cursor?
4:48:11
nyef
hooman: Umm... No, not for the function CALL you're writing, the function DEFINITION you're writing.
4:48:14
hooman
https://www.common-lisp.net/project/slime/doc/html/slime_002dautodoc_002dmode.html -- not in seperate panes by default however
4:49:44
nyef
"Oh, you're looking at the implementation of DEFSETF. Here's the specification for it."
4:51:49
hooman
it would definately inspire doc writing. perhaps hijacking autodoc/eldoc to go in reverse (it can find the docs, cant it, same with slime hyperspec search) could be trivial using go-to-first-toplevel-sexp elisp instead of symbol-at-point . dreams
4:52:22
hooman
what if we could generate some english template docs based on a function definition, and fill in some blanks and refine it (with macros obv.)
4:53:29
hooman
and then i also wonder, what if we could then reverse-generate some lisp forms, based on some rudimentary english documentation like grammar/words ?
4:53:45
nyef
Heh. The real trick would be to take the definition, infer the operational semantics from that, and then come up with an english description automatically.
4:54:09
nyef
But that's definitely further down the AI path than I'm looking to head in the immediate future.
4:54:24
hooman
not sure if its a trick... honestly, get like 100 people to write docs for functions, then use machine learning stuff to train with that... in languages, too
4:55:29
hooman
i know its time to get back to work when i start to think about procedurally generating programming languages again
8:20:30
jackdaniel
could you comment on formatting-table issue you have filled? https://github.com/robert-strandh/McCLIM/issues/93
8:44:54
scymtym
jackdaniel: maybe i'm imagining this, but in the "Bordered-Output" demo, didn't the first Oval change its background to white when highlighted? now it just seems to flicker briefly
8:47:19
jackdaniel
scymtym: thanks. "Bordered-Output"? you mean `tables with borders` or `border styles tests`?
8:49:16
scymtym
the demodemo button is labeled "Border Styles Test", the window it opens has the title "Bordered-Output"
8:51:37
jackdaniel
loke`: I have left another comment there – yes, I understand better what you meant now
8:54:37
jackdaniel
basically this isn't something directly caused by my changes, it just happens, that highlighting-output-border uses the same code as standard-output-border. specializing method for highlight to use old behavior may work just fine (not sure yet)
9:01:29
jackdaniel
yes, thanks. I'm not sure if it will be easy, that will require at least two passes across all rows (some columns may rival for space, how do we arbiter that – etc), but now it is more clear to me
9:05:25
jackdaniel
unless we take greedy heuristic and we starve remaining columns if one takes most of the space
9:06:57
loke`
I started looking at it some time ago, and I also came to the conclusion that at least two passes are needed (well, two passes in the case when there is a contention)
9:07:53
jackdaniel
I know how to implement that (and if we allow situation, where remaining columns are space-starved, it requiers just one pass), but I'll wait for MatthewRock, so he doesn't feel like I have stolen it from him
10:08:30
jackdaniel
if we have equalize-width t, then obviously all columns take (min (/ pane-width n) biggest-width), if we don't, then (for greedy approach) – mth-column takes (min col-requested-width (- pane-rest-width (* rest-cols min-width)))
10:09:47
loke`
jackdaniel: But there is no way of knowing the requested width of a column without rendering it
10:10:18
loke`
And if a column turns out to request too much width, then it needs to be re-rendered with a narrower width.
10:11:52
jackdaniel
loke`: you provide in both cases :max-width as approprietly (/ pane-width n) and (- pane-rest-width (* rest-cols min width)), and then you judge, what is smaller
10:15:34
loke`
jackdaniel: How can they be known? Let's say you have columns A and B. Pane width is 100. B contains nothing but the letter "X" (i.e. super narrow) and has width 5. How will you know that the max width for A will be 95 by the time you render it? This information isn't known until B has been rendered.
10:18:33
jackdaniel
as I said, greedy approach assumes, that you assign space as you go. First you render A (equalize-width is NIL) – you provide :max-width (- pane-width (* 1 col-min-width)) ; ("1", because there is one remaining column)
10:28:58
jackdaniel
so when you render B, you have :max-width (- pane-width all-previously-rendered-columns (* 0 col-min-width)) ; ("0", because tehre is no columns left)
10:35:21
loke`
jackdaniel: But if A requests 90% of the width, you won't know if that's going to be acceptable until you render B.
10:36:07
loke`
It may be that B only requetss a width of 5, in which case all is good. But if B requests 20, then you need to re-render A with a max width of 80
10:41:40
loke`
jackdaniel: I'm pretty sure it doesn't work that way in HTML. Let me give another example to highlight it. Let's say you have two columns. Total width 100. Both column A and B want to have a width of 60. With your proposal, A wiuld be 60 and B would be 40. I'd like them to both be 50.
10:42:35
loke`
jackdaniel: But that will give a bad result if A wants to be 80 and B wants to be 10.
10:47:56
jackdaniel
arranging columns as you suggest isn't well defined in my understanding. How do you decide, if they should have equal width (60 vs 40 -> 50 vs 50) vs (80 vs 20 -> 80 vs 20)?
10:51:01
loke`
jackdaniel: That would depend on the weight of each column. The weight by default should be equal for all.
10:52:15
loke`
if one column has weiight 2 and the rest have 1, then that column get twice as much space than the rest.
10:58:12
loke`
That's essentially what I'd like. The weight would be useful, but to be honest I rarely used it in Java
11:00:38
jackdaniel
as you have mentioned, this algorithm would require displaying each cell content twice. I'm sure we can't do that unless we rewrite it as incremental-output which would be a big task I think (without breaking the spec that is)
11:04:11
loke`
jackdaniel: Hmm... does it? Oh wait... Yes. Incremental output contains the newlines as well.