4 ms·

My critique was more on the visual side of things. I think it matters. That said, onto your comment: I liked the presentation. The @ notation is kinda neat and

My critique was more on the visual side of things. I think it matters. That said, onto your comment: I liked the presentation. The @ notation is kinda neat and elegant, and no doubt enabled by the ridiculous power macros give you in terms of modifying how everything is parsed. It's cool that it's implemented as a DrScheme lang, and it can run and is all code-is-data-y, and it's not a totally separate language. However, I don't really see anything in here that any modern document processor (say http://sphinx-doc.org/ http://sphinx-doc.org/) can't perform. The second-last question brings up a great point that when you tightly couple your documentation language with the platform (PLT), you run the risk of it being a PITA to use it to document other languages. I think the presenter's solution of automatically creating stub classes and such is really unsatisfactory and kinda kills the benefits. So there you have it, there are pluses and minuses. I think Scribble is neat, but it's really not all that out of the ordinary.. It's definitely not true that "nothing comes close".

brudgers 13y ago
Beware the Blub Paradox. http://www.paulgraham.com/avg.html http://www.paulgraham.com/avg.html
- makmanalp 13y ago
  I've read "beating the averages" about a billion times, along with all the other PG essays. I was (and still am) a fan. I took several classes using PLT scheme and I've used PLT scheme for a reasonable amount for other tasks (wasn't called racket then). I've also dabbled with some lisps. I've read the little schemer, I've went through the wizard book. I've written the obligatory metacircular evaluator. All this got me excited. Over the years though, I've done my best to learn the lessons and move on. Is it really a surprise that lisp, an aged tool of refined elegance, was a competitive advantage over the other popular languages in 1997, which were still in their neanderthal phase? I'm not sure if the difference is that huge these days though. While in the olden days languages seemingly refused to learn from the teachings of lisp, it seems today they steal from lisp like pop artists steal from each other. Say, a ruby DSL with blocks and other tricks is not as flexible as a defmacro based lisp one, but could there maybe be a tradeoff here? Writing in lisps give me what I call the intellectual warm-fuzzies. I get to use many elegant tools to form abstractions upon abstractions to create the DSL for my problem domain. I like that. Some call it doing the Right Thing. The polar opposite of duct-tape programming if you will. A quote from the article: "to translate this program into C++ they literally had to write a Lisp interpreter [so basically a lisp-to-c++ compiler]". This is exactly the sort of thing I'm talking about. It's cute. It's the Right Thing. Rewriting the code by hand in C++ is for plebians. And, given enough code, maybe writing the lisp-to-c++ compiler is less effort than a rewrite initially. Maybe. I'll allow the benefit of the doubt. But what about the machine-outputted C++? Is the code idiomatic? Is it performant? Who wants to maintain machine generated code? Who wants to maintain a custom compiler? Maybe none of these are problems, but my vote is that it's unlikely. The blub paradox applies much more strongly (or maybe I could say "only applies") when you haven't been exposed. When you, in your arrogance, refuse to try something different. I've traveled up and down the proverbial ladder, and I know where I'm comfortable. For now. I suspect it'll change sooner or later. What astounds me is the arrogance to claim that lisp(s) is the One True Language, and anyone who doesn't agree Just Doesn't Get It. It's like the audacity a religious person has in claiming that their god is the one and only, in effect taking for idiots all the millions of remaining people who ever existed and sincerely believed in their own creation stories. What are the chances that everyone is stupid and you're the only enlightened one? In response, I give you the Bipolar Lisp Programmer: http://www.lambdassociates.org/blog/bipolar.htm http://www.lambdassociates.org/blog/bipolar.htm
samth 13y ago
What sets scribble apart are: * That it's a full programming language, unlike systems like Markdown, or Sphinx, or JavaDoc, or other similar systems. But it also doesn't sacrifice being easy to write, the way that text is easy to write. * That is works properly with binding. If you're documenting a function, you want to document the correct one -- that's handled with binding, the same way it works when programming. When you're writing an example, the same should be true -- again, handled with binding in Scribble. This works for _programs_, not just identifiers, which is what it looks like Sphinx does. That's why, for example, every single identifier in the examples on http://racket-lang.org http://racket-lang.org is hyperlinked to its documentation. If you go to http://docs.python.org/3/tutorial/controlflow.html http://docs.python.org/3/tutorial/controlflow.html , the examples aren't hyperlinked at all.
- makmanalp 13y ago
  I think the binding is really the big thing here. That basically the whole module environment is also available to scribble since it is also legitimate code, and it's being executed by the same interpreter, in essence. I'm unconvinced that this is not possible otherwise though. If you're parsing the darn language to get to the AST to generate all the module names, contents, etc, I don't see why you couldn't have access to all that info when generating an example code block. Example: http://wtf.tw/etc/pygments/pygments/formatters/html.py.html http://wtf.tw/etc/pygments/pygments/formatters/html.py.html Although I don't know why it's not more common.
  - samth 13y ago
    Right, people have certainly implemented hyperlinked versions of code by re-implementing the parser etc. LXR is an excellent example of this. What sets Scribble apart is that * It's a documentation system, not just a code formatter. * It's a programmable documentation system, and the code that _implements_ your documentation is kept appropriately separate from the code that you are documenting. This makes use of Racket's support for phases. * That it doesn't re-implement the parser etc, but can use the built-in one, because of Racket's macros. And, as you say, even if none of this was unique, there's the fact that Racket does it, and has 500k lines of documentation, all done comprehensively in this style.

brudgers 13y ago

Beware the Blub Paradox. http://www.paulgraham.com/avg.html http://www.paulgraham.com/avg.html

makmanalp 13y ago
I've read "beating the averages" about a billion times, along with all the other PG essays. I was (and still am) a fan. I took several classes using PLT scheme and I've used PLT scheme for a reasonable amount for other tasks (wasn't called racket then). I've also dabbled with some lisps. I've read the little schemer, I've went through the wizard book. I've written the obligatory metacircular evaluator. All this got me excited. Over the years though, I've done my best to learn the lessons and move on. Is it really a surprise that lisp, an aged tool of refined elegance, was a competitive advantage over the other popular languages in 1997, which were still in their neanderthal phase? I'm not sure if the difference is that huge these days though. While in the olden days languages seemingly refused to learn from the teachings of lisp, it seems today they steal from lisp like pop artists steal from each other. Say, a ruby DSL with blocks and other tricks is not as flexible as a defmacro based lisp one, but could there maybe be a tradeoff here? Writing in lisps give me what I call the intellectual warm-fuzzies. I get to use many elegant tools to form abstractions upon abstractions to create the DSL for my problem domain. I like that. Some call it doing the Right Thing. The polar opposite of duct-tape programming if you will. A quote from the article: "to translate this program into C++ they literally had to write a Lisp interpreter [so basically a lisp-to-c++ compiler]". This is exactly the sort of thing I'm talking about. It's cute. It's the Right Thing. Rewriting the code by hand in C++ is for plebians. And, given enough code, maybe writing the lisp-to-c++ compiler is less effort than a rewrite initially. Maybe. I'll allow the benefit of the doubt. But what about the machine-outputted C++? Is the code idiomatic? Is it performant? Who wants to maintain machine generated code? Who wants to maintain a custom compiler? Maybe none of these are problems, but my vote is that it's unlikely. The blub paradox applies much more strongly (or maybe I could say "only applies") when you haven't been exposed. When you, in your arrogance, refuse to try something different. I've traveled up and down the proverbial ladder, and I know where I'm comfortable. For now. I suspect it'll change sooner or later. What astounds me is the arrogance to claim that lisp(s) is the One True Language, and anyone who doesn't agree Just Doesn't Get It. It's like the audacity a religious person has in claiming that their god is the one and only, in effect taking for idiots all the millions of remaining people who ever existed and sincerely believed in their own creation stories. What are the chances that everyone is stupid and you're the only enlightened one? In response, I give you the Bipolar Lisp Programmer: http://www.lambdassociates.org/blog/bipolar.htm http://www.lambdassociates.org/blog/bipolar.htm

samth 13y ago

What sets scribble apart are: * That it's a full programming language, unlike systems like Markdown, or Sphinx, or JavaDoc, or other similar systems. But it also doesn't sacrifice being easy to write, the way that text is easy to write. * That is works properly with binding. If you're documenting a function, you want to document the correct one -- that's handled with binding, the same way it works when programming. When you're writing an example, the same should be true -- again, handled with binding in Scribble. This works for _programs_, not just identifiers, which is what it looks like Sphinx does. That's why, for example, every single identifier in the examples on http://racket-lang.org http://racket-lang.org is hyperlinked to its documentation. If you go to http://docs.python.org/3/tutorial/controlflow.html http://docs.python.org/3/tutorial/controlflow.html , the examples aren't hyperlinked at all.

makmanalp 13y ago
I think the binding is really the big thing here. That basically the whole module environment is also available to scribble since it is also legitimate code, and it's being executed by the same interpreter, in essence. I'm unconvinced that this is not possible otherwise though. If you're parsing the darn language to get to the AST to generate all the module names, contents, etc, I don't see why you couldn't have access to all that info when generating an example code block. Example: http://wtf.tw/etc/pygments/pygments/formatters/html.py.html http://wtf.tw/etc/pygments/pygments/formatters/html.py.html Although I don't know why it's not more common.
- samth 13y ago
  Right, people have certainly implemented hyperlinked versions of code by re-implementing the parser etc. LXR is an excellent example of this. What sets Scribble apart is that * It's a documentation system, not just a code formatter. * It's a programmable documentation system, and the code that _implements_ your documentation is kept appropriately separate from the code that you are documenting. This makes use of Racket's support for phases. * That it doesn't re-implement the parser etc, but can use the built-in one, because of Racket's macros. And, as you say, even if none of this was unique, there's the fact that Racket does it, and has 500k lines of documentation, all done comprehensively in this style.