Add a tutorial for non-Lisp users

alexherbo2 commented 5 years ago

With meaningful examples.

Ambrevar commented 5 years ago

It's a good idea!

I'll work on it, but eventually I'd like to have it all "embedded and discoverable".

For instance, we could have a generic "help" command, and one of the topics could be "Lisp" (or "config" or "init.lisp") and this would prompt a page with a crash course, some examples and some links to more documentation (e.g. Practical Common Lisp).

Thoughts?

alexherbo2 commented 5 years ago

I can understand the examples, but not in the details, and I’m lost to know where a particular function comes from. Is Common Lisp, Next or a package?

There is a ton of functions and wording in the function names themselves. When I have to write something myself, I have the feeling to not know which is the right function to use, and the idiomatic way to do things.

A good starting point could be to add a link to the documentation of each function – like MDN does for JavaScript.

In addition, and to answer #204, web developers know JavaScript, but not necessarily Lisp. I guess a document From JavaScript to Common Lisp, with equivalents could be helpful.

Example – Collect <input> elements in the document:

JavaScript

const inputs = document.querySelectorAll('input')

Lisp

; How to do?

jmercouris commented 5 years ago

I'm not sold on the idea of a "Common Lisp for JavaScript Developers" document. The programming languages are very different. Furthermore, we would have to write a document for every popular programming language. I believe this is a large task, and outside of the scope of Next :(

I do think there is a good middle ground though: I can recommend many great resources on learning how to write Common Lisp. We could include links in our documentation and a mini tutorial for people to get started. Many people before us have written great guides, documentation, and tutorials that could really help. Maybe this would suffice?

Interested in your thoughts,

thanks,

-John

alexherbo2 commented 5 years ago

I would like to hear the thoughts of other users as well.

Personally, I still think it makes sense, because JavaScript is the primary language to interact with the DOM.

jmercouris commented 5 years ago

There is no javascript anywhere in the codebase, we are only using parenscript. Please see the following URL for more information: https://common-lisp.net/project/parenscript/

Ambrevar commented 5 years ago

Well, I won't lie: if you want to hack Next, you'll need to know some Common Lisp :) (See below for a recommendation.) If you've never hacked in a Lisp language before, this can be a little demanding at first. But once you've acquired the basics, much of it will become straightforward.

Lisp languages, by their very nature, are heavily interactive. In other words: the code is much easier to explore from a good REPL like SLIME. With the right tooling it's very straightforward to "go to definition" or "show documentation". This will also answer your question about where functions come from.

I can help with setting up SLIME (or SLY) if you want. If you use another editor than Emacs, I know there are other Common Lisp modules for them (Vim has at least 2).

I am not sure we need something like MDN. The documentation can be explored interactively (for now mostly from the REPL -- but I hope that Next will do better in the future with respect to explorability). Should we need a web-based reference, this can be provided by services like http://quickdocs.org/.

Regarding a Javascript-to-Lisp tutorial: well, we exclusively use Parenscript (https://common-lisp.net/project/parenscript/) to send Javascript to the web renderer, which is basically lispish syntax for Javascript. It mostly maps 1 to 1, so there is not much to document here, beside improving Parenscript documentation. Regarding your question:

const inputs = document.querySelectorAll('input')

With Parenscript, that would be

(ps:chain document (query-selector-all input))

About programming in Common Lisp: I suggest starting with a book like Practical Common Lisp (free online: http://www.gigamonkeys.com/book/). I don't think many parallels can be drawn between Javascript and Common Lisp: the languages might be too different.