cheatsheet / reference card for lowering learning curve

[aspiers]

I'm just learning lispy for the first time, after using paredit for a long time, and it's mind-blowingly cool! Furthermore, the README.md and function reference are both excellent.

Having said that, given the huge number of commands to learn, I think the learning curve could be shrunk quite a bit by offering a condensed cheatsheet / reference card which shows the top 30--50 most commonly needed commands within a single page, logically grouped by functionality, e.g.

• Movement / navigation
  • into special mode
  • by list structure
  • by definitions / symbols / tags
  • by previous navigation history
• Insertion
• Deleting / killing
• Modifying sexp structure
• Modifying appearance
  • Whitespace changes (indentation, line breaks etc.)
  • Narrowing / widening

In other words, perhaps something similar to the paredit cheatsheet. In fact, given that the paredit cheatsheet is GPL v3, perhaps that could even be forked to produce a lispy version.

This suggestion is motivated by the following reasons:

• The README.md groups the key bindings and corresponding commands quite nicely by functionality (e.g. "Operating on lists" vs. "Operating on regions", and the subsections within those). Consequently it serves as a great intro. However, over the first few hours/days of usage, users need to keep referring back to this to help the new key bindings and muscle memory sink in. Since the README.md is a fairly long document, it is not possible to see a quick summary of the most commonly needed commands within a single view, so this learning process results in a quite a lot of scrolling up and down through it.

• The function reference is really nice in how a) it groups key bindings into the G / az / AZ / x and b) how comprehensive and clearly written it is, but it does not offer the logical grouping by functionality mentioned above. This means that every time the user has a question like "remind me which key lets me quickly jump to [...] ?", it takes them a little longer to find the answer.

Does this make sense and sound like a reasonable suggestion?

[aspiers]

OK, here's my first, unpolished attempt at a functionally grouped cheatsheet. It's in org format for now, but of course ideally this would be compressed into a compact single page reference card like the paredit cheatsheet linked above:

* Movement / navigation
*** into special mode
    | ]   | backward                     |
    | ]   | forward                      |
    | C-3 | right                        |
    | "   | right-no-string              |
    | C-8 | insert () after current sexp |

    See also [[*Deleting / killing][Deleting / killing]]
*** by list structure
    | f     | forward down level into list     |
    | h / l | left / right up level            |
    | j / k | down / up at same level          |
    | d     | different (opposite end of sexp) |
    | )     | up level and right               |
*** beginning / end
    | C-a / C-e | beginning / end of line |
    | A         | beginning of defun      |
*** marking a region
    | m | mark sexp |
    | a | ace mark symbol within top-level form |
*** grow / shrink region
    | h / l | mark parent with point on left/right |
    | < / > | shrink / extend sexp                 |
*** unmarking a region
    | m | unmark region |
*** by definitions / symbols / tags
    | g / G   | jump to tag in dir/file |
    | F / M-. | jump to symbol          |
*** by occurrence
    | q | ace-jump to paren within top-level form   |
    | Q | ace-jump to char within top-level form    |
    | - | quickjump to subword within top-level form |
*** by previous navigation history
    | b       | move back in history  |
    | D / M-, | jump back from symbol |
* Insertion
*** structure
    | (  | parens   |
    | {  | braces   |
    | }  | brackets |
    | "  | quotes   |
    | :  | ?        |
    | \^ | ?        |
*** whitespace
    | SPC | intelligent space insertion |
    | C-m | newline and indent          |
*** code
    | xb | (let () ...) |
* Deleting / killing
  | C-k   | kill               |
  | M-d   | kill word          |
  | C-,   | kill sexp at point |
  | M-k   | kill sentence      |
  | M-DEL | backward kill word |
* Modifying sexp structure
  | r         | raise                                               |
  | s / w     | move down / up                                      |
  | z         | "knight"                                            |
  | < / >     | barf / slurp                                        |
  | M-j / +   | split / join                                        |
  | c         | clone                                               |
  | C         | convolute                                           |
  | S / C-u " | stringify / quotes                                  |
  | ; / C-u ; | comment / uncomment                                 |
  | H         | quick jump and replace symbol within top-level form |
  | t         | teleport current sexp/region somewhere else         |
* Refactorings / code operations
  | xc | (if ...) => (cond ...)      |
  | xi | (cond ...) => (if ...)      |
  | xd | (lambda ...) => (defun ...) |
  | xf | inline function / macro     |
  | xu | unbind let-bound variable   |
* Copy / paste
  | n   | copy region preserving it          |
  | P   | destructive paste replacing region |
* Modifying appearance
  | i     | indent (prettify)         |
  | I     | shift-tab                 |
  | v     | recenter current sexp     |
  | O / M | oneline / multiline       |
  | N / W | narrow / widen            |
  | y     | occur                     |
* Help
  | C-1 | show docs in other buffer |
  | C-2 | show fn arguments inline  |
  | xh  | describe                  |
* Version control
  | B |                   |
  | u | undo last command |
* Execution
  | e      | eval                                         |
  | p      | eval in other window's context               |
  | E      | eval and insert                              |
  | edebug | xe                                           |
  | Z      | exit edebug                                  |
  | xj     | prepare to debug current function invocation |
  | xT     | ert                                          |

[aspiers]

Related thought: if the above reference card should come into existence, adding a key-binding to lispy-mode to launch a viewer for it would be really cool. For instance, if it's a PDF, it could be opened in a separate buffer.

[alphapapa]

I think this is a great idea. :) I took the liberty of putting the keys in verbatim syntax so they look a bit better in HTML:

* Movement / navigation

*** into special mode

    | =]=   | backward                     |
    | =]=   | forward                      |
    | =C-3= | right                        |
    | ="=   | right-no-string              |
    | =C-8= | insert () after current sexp |

    See also [[*Deleting / killing][Deleting / killing]]

*** by list structure

    | =f=     | forward down level into list     |
    | =h / l= | left / right up level            |
    | =j / k= | down / up at same level          |
    | =d=     | different (opposite end of sexp) |
    | =)=     | up level and right               |

*** beginning / end

    | =C-a / C-e= | beginning / end of line |
    | =A=         | beginning of defun      |

*** marking a region

    | =m= | mark sexp |
    | =a= | ace mark symbol within top-level form |

*** grow / shrink region

    | =h / l= | mark parent with point on left/right |
    | =< / >= | shrink / extend sexp                 |

*** unmarking a region

    | =m= | unmark region |

*** by definitions / symbols / tags

    | =g / G=   | jump to tag in dir/file |
    | =F / M-.= | jump to symbol          |

*** by occurrence

    | =q= | ace-jump to paren within top-level form   |
    | =Q= | ace-jump to char within top-level form    |
    | =-= | quickjump to subword within top-level form |

*** by previous navigation history

    | =b=       | move back in history  |
    | =D / M-,= | jump back from symbol |

* Insertion

*** structure

    | =(=  | parens   |
    | ={=  | braces   |
    | =}=  | brackets |
    | ="=  | quotes   |
    | =:=  | ?        |
    | =\^= | ?        |

*** whitespace

    | =SPC= | intelligent space insertion |
    | =C-m= | newline and indent          |

*** code

    | =xb= | (let () ...) |

* Deleting / killing

  | =C-k=   | kill               |
  | =M-d=   | kill word          |
  | =C-,=   | kill sexp at point |
  | =M-k=   | kill sentence      |
  | =M-DEL= | backward kill word |

* Modifying sexp structure

  | =r=         | raise                                               |
  | =s / w=     | move down / up                                      |
  | =z=         | "knight"                                            |
  | =< / >=     | barf / slurp                                        |
  | =M-j / +=   | split / join                                        |
  | =c=         | clone                                               |
  | =C=         | convolute                                           |
  | =S / C-u "= | stringify / quotes                                  |
  | =; / C-u ;= | comment / uncomment                                 |
  | =H=         | quick jump and replace symbol within top-level form |
  | =t=         | teleport current sexp/region somewhere else         |

* Refactorings / code operations

  | =xc= | (if ...) => (cond ...)      |
  | =xi= | (cond ...) => (if ...)      |
  | =xd= | (lambda ...) => (defun ...) |
  | =xf= | inline function / macro     |
  | =xu= | unbind let-bound variable   |

* Copy / paste

  | =n=   | copy region preserving it          |
  | =P=   | destructive paste replacing region |

* Modifying appearance

  | =i=     | indent (prettify)         |
  | =I=     | shift-tab                 |
  | =v=     | recenter current sexp     |
  | =O / M= | oneline / multiline       |
  | =N / W= | narrow / widen            |
  | =y=     | occur                     |

* Help

  | =C-1= | show docs in other buffer |
  | =C-2= | show fn arguments inline  |
  | =xh=  | describe                  |

* Version control

  | =B= |                   |
  | =u= | undo last command |

* Execution

  | =e=      | eval                                         |
  | =p=      | eval in other window's context               |
  | =E=      | eval and insert                              |
  | =edebug= | xe                                           |
  | =Z=      | exit edebug                                  |
  | =xj=     | prepare to debug current function invocation |
  | =xT=     | ert                                          |

[pierre-rouleau]

I like the idea too. Let me know if/where you'll host this page. I want to add it as a reference to what I built in my system. I have created a PDF file that is not as quick a reference but tries to provide the information in a tabular fashion with hyperlinks for more info and uses colors and icons to identify things. See my GitHub rendered Lispy PDF. The raw version can be rendered in browser like Firefox and you will see it has several links in it. I'm still working on that file to include as much as possible.

[aspiers]

@alphapapa commented on December 19, 2020 8:21 PM:

I think this is a great idea. :) I took the liberty of putting the keys in verbatim syntax so they look a bit better in HTML:

Thanks. Here's an updated version with a few more entries:

* Movement / navigation

*** into special mode

    | =[=   | backward                     |
    | =]=   | forward                      |
    | =M-o= | left-maybe                   |
    | =C-3= | right                        |
    | ="=   | right-no-string              |
    | =C-8= | insert () after current sexp |

    See also [[*Deleting / killing][Deleting / killing]]

*** by list structure

    | =f=     | forward down level into list     |
    | =h / l= | left / right up level            |
    | =j / k= | down / up at same level          |
    | =d=     | different (opposite end of sexp) |
    | =)=     | up level and right               |

*** beginning / end

    | =C-a / C-e= | beginning / end of line |
    | =A=         | beginning of defun      |

*** marking a region

    | =m= | mark sexp |
    | =a= | ace mark symbol within top-level form |

*** grow / shrink region

    | =h / l= | mark parent with point on left/right |
    | =< / >= | shrink / extend sexp                 |

*** unmarking a region

    | =m= | unmark region |

*** by definitions / symbols / tags

    | =g / G=   | jump to tag in dir/file |
    | =F / M-.= | jump to symbol          |

*** by occurrence

    | =q= | ace-jump to paren within top-level form   |
    | =Q= | ace-jump to char within top-level form    |
    | =-= | quickjump to subword within top-level form |

*** by previous navigation history

    | =b=       | move back in history  |
    | =D / M-,= | jump back from symbol |

*** by comment outline
    | =J / K= | down / up heading |
    | =L=     | goto child        |
    | =N / W= | narrow / widen    |
* Insertion

*** structure

    | =(=  | parens   |
    | ={=  | braces   |
    | =}=  | brackets |
    | ="=  | quotes   |
    | =:=  | ?        |
    | =\^= | ?        |

*** whitespace

    | =SPC= | intelligent space insertion |
    | =C-m= | newline and indent          |

*** code

    | =xb= | (let () ...) |

* Deleting / killing

  | =C-k=   | kill               |
  | =M-d=   | kill word          |
  | =C-,=   | kill sexp at point |
  | =M-k=   | kill sentence      |
  | =M-DEL= | backward kill word |

* Modifying sexp structure

  | =r=         | raise                                               |
  | =s / w=     | move down / up                                      |
  | =z=         | "knight"                                            |
  | =< / >=     | barf / slurp                                        |
  | =M-j / +=   | split / join                                        |
  | =c=         | clone                                               |
  | =C=         | convolute                                           |
  | =xr=        | eval and replace                                    |
  | =S / C-u "= | stringify / quotes                                  |
  | =; / C-u ;= | comment / uncomment                                 |
  | =xR=        | reverse list                                        |
  | =H=         | quick jump and replace symbol within top-level form |
  | =t=         | teleport current sexp/region somewhere else         |

* Refactorings / code operations

  | =xb= | let-bind variable           |
  | =xc= | (if ...) => (cond ...)      |
  | =xi= | (cond ...) => (if ...)      |
  | =xd= | (lambda ...) => (defun ...) |
  | =xl= | (defun ...) => (lambda ...) |
  | =xf= | inline function / macro     |
  | =xF= | let-flatten                 |
  | =xt= | view test                   |
  | =xu= | unbind let-bound variable   |

* Copy / paste

  | =n=   | copy region preserving it          |
  | =P=   | destructive paste replacing region |

* Modifying appearance

  | =i=     | indent (prettify)         |
  | =I=     | shift-tab                 |
  | =v=     | recenter current sexp     |
  | =O / M= | oneline / multiline       |
  | =N / W= | narrow / widen            |
  | =y=     | occur                     |

* Help

  | =C-1= | show docs                |
  | =C-2= | show fn arguments inline |
  | =xh=  | describe                 |

* Version control

  | =B= |                   |
  | =u= | undo last command |

* Execution

  | =e=      | eval                                         |
  | =p=      | eval in other window's context               |
  | =xr=     | eval and replace                             |
  | =E=      | eval and insert                              |
  | =edebug= | xe                                           |
  | =Z=      | exit edebug                                  |
  | =xj=     | prepare to debug current function invocation |
  | =xT=     | ert                                          |

[aspiers]

@Pierre Rouleau commented on March 6, 2021 10:19 PM:

I like the idea too. Let me know if/where you'll host this page.

Ideally it would be included in this official repository so that it could be maintained alongside any changes in the key bindings. I'm not sure whether it would be accepted, but it's worth trying that first.

I want to add it as a reference to what I built in my system. I have created a PDF file that is not as quick a reference but tries to provide the information in a tabular fashion with hyperlinks for more info and uses colors and icons to identify things. See my GitHub rendered Lispy PDF. The raw version can be rendered in browser like Firefox and you will see it has several links in it. I'm still working on that file to include as much as possible.

Very nice indeed! It would be good to have both your longer more detailed PDF and a shorter quick-reference cheatsheet. The paredit cheatsheet is the perfect example of what I have in mind.

[pierre-rouleau]

@aspiers

Very nice indeed! It would be good to have both your longer more detailed PDF and a shorter quick-reference cheatsheet. > The paredit cheatsheet is the perfect example of what I have in mind.

Thanks! As you might have noticed my PDF file has a little bit of information related to my system though. It is part of a larger set of PDF files on different Emacs topics. I could make a copy of the Lispy related one with that info removed if it was necessary. Also, when I started writing that I looked for different markups that would allow me to create what I did relatively easily as I was learning Emacs, and I picked the macOS Numbers spreadsheet application to do it. So the source is binary. For the moment my Numbers file has a large number of tabs inside it and about 90 are published. I could extract that single sheet in a separate file and publish that file too allowing people to modify it further but they would have to use Numbers or something compatible with it (I don't know if such tool exists).

The alternative would just be to create hyperlinks between the various documents.

[aspiers]

Ah I see. Yeah, that file format unfortunately prohibits any collaboration. Ideally you could convert it to HTML or another open format. I've never used Numbers but maybe it allows export to ODF? Or at least to .xlsx from which you could convert to ODF. But any spreadsheet format is not really conducive to collaboration, except for CSV which obviously doesn't support any of your nice formatting.

The paredit cheatsheet uses TeX which is a great option for this kind of thing, but it does have a learning curve.

[pierre-rouleau]

I have looked to find ways to export to other formats that would retain all the formatting, but have not found anything so far. I would have looked in TeX but I'm not sure I can do the same thing. And now I have lots of data... The format Numbers natively export to are PDF, CSV, TSV, Excel. I tried the ODF via Excel but the layout was modified beyond my desire to spend yet more time reformatting. Numbers is more flexible than Excel for the type of formatting I did so far.

[pierre-rouleau]

BTW, I have put all the information I could find without really looking into the lispy code. There's 3 commands I have not found anything on it. Do you know where these 2 would be documented?

• lispy-cleanup
• lispy-x-more-verbosity

[aspiers]

I think I had to dig into the code to figure out some stuff. Just search the repository to see whether they're documented.

[pierre-rouleau]

I read the source code and added more info. lispy-cleanup removes commented lines that start with ;; =>

As for lispy-x-more-verbosity it brings up a small menu to get to various commands. I updated my PDF with most of it.

I tried converting the PDF to HTML5 via several on-line services, but they failed as that was the case when I tried it several months ago. So for now, once you have found a home for your quicksheet I'll add a link to it in my PDF.