Below are some random examples. It's hard for me to give you a fuller answer as I now do know some Leo and so I'm less confused when I read the docs - so I can't easily point out problems.
In the main tutorial page, the script in Accessing Outline Data doesn't work - it's missing a parenthesis. It's not clear to me how to even run the script. I happen to know Ctrl-B, but is it in the tutorial? I took the script and put it in a @button node, and the button didn't show up. I'm not sure if something is wrong with my Leo or the docs. It may be obvious, but it would be nice for that code snippet to have @language python. In the scripting tutorial, it would be nice if it pointed out that .h and .b refer to the headline and body. I know most will figure it out, but I think it should be spelled out explicitly. Will any command I create that manipulates texts/nodes automatically be undo-able? If not, what do I need to do to ensure it is? A lot of stuff in the cheat sheet with regards to scripting is just a list with no explanation. Asking people to look at the source code to figure it out is not documenting anything. If all these classes/functions had good docstrings, one could autogenerate the docs using a script. What is an ivar? I could not get unit testing to work in a way that is useful for me (see my other email on the mailing list). The Miscellany of Scripts page used to have scripts that didn't work. I think the ones I complained about may have been fixed. In general, though, I think all the scripting docs are disorganized. Some of it is in one page, some in another, with no clear structure. I have to keep going to various pages and hitting Ctrl-F. The commands reference page mentions macros. Do they work? Last time I tried they did not. That page mentions Emacs behavior commands like kill and yank. Yet yank does *not* behave like it does in Emacs. In Emacs, if you yank, and then yank again, it will replace the region. Here it keeps appending. How do I comment and uncomment multiple lines? Is that documented? I recently went through all the settings in Leo, and wow, there's quite a bit of good stuff there. How much of that is in the docs? Had I not decided to look at *all* the settings, I would not have discovered many of them. I'd like a page that lists all the settings, with descriptions. Many @settings nodes have descriptions, and many others do not, so I have little idea as to what they do. Part of the documentation effort should be to put a good description of each one. Is Leo "aware" of all its settings? Is it not possible then to have a script that will generate documentation for all Leo's settings as an HTML (or part of the docs' rst) - and make sure this is on the web site. Trust me, it would make Leo a lot more useable if people had a page where they could see all the settings and just search for what they want. Oh, and some settings appear to be "fake" - as in they are in the settings file, but when I do a cff in the code base all references to those settings are commented out. Staleness is a common problem. I would even argue that there should be a script to ensure that all the settings in @settings actually ARE settings. And in the other direction, if Leo has a setting, ensure it exists in the main settings file. We have various directives. Can I create my own? This may well be documented, but I don't know if it is. Quite a lot of functions in the code base have no docstring. And the code is not that easy to read as so many variables are short single letter variables. I think good docstrings on functions would help a lot. I want to add support for a new language (syntax highlighting, etc). How well is this documented? Does it just say to look at the source code? Are all the default keybindings documented? Leo is almost tragic in how powerful it is, and how much its adoption is held back by poor documentation. Good documentation will be a major endeavour, but well worth it. On Wednesday, October 10, 2018 at 12:10:38 PM UTC-7, Edward K. Ream wrote: > On Wed, Oct 10, 2018 at 1:22 PM <[email protected] <javascript:>> wrote: > > > My dream is that the documents be vastly improved. > > Please tell me what you think should be added to CheatSheet.leo, or to the > tutorials. > > Typing completion in the minibuffer is a good way to discover commands. > > After that, leoPyRef.leo contains all the answers. > > Edward > -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/leo-editor. For more options, visit https://groups.google.com/d/optout.
