> > You have to insert calls to u.beforeSomething and u.afterSomething, where > u is c.undoer and "Something" is one of a list of possible actions. The > complete list is in leoUndo.py. In essence, the "before" method saves the > *relevant* data before executing the command, and the "after" method > saves the corresponding data after executing the command. Saving only part > of the outline's data is an absolutely essential optimization. >
How do I know which commands I write are automatically undoable and which ones are not? My script to alter commenting behavior seems undoable without my putting any effort into making it so. Macros have been removed. Leo's scripting is much more powerful. I hope you'll remove it from the docs, then. Going off topic, I view this as a false dichotomy. One can have macros /and/ scripting. Certainly scripting is more powerful, but for most of the things I use macros in Emacs, it would be a step backwards to write a script. Most of the time I define and run a macro in under a minute. Take this example. I have over a 100 lines of "Name",Value:Parent and I want to transform each line to: Value: Parent -> Name It's trivial to define a macro and run this in a few seconds. Regarding yank, at least the docs should indicate that it doesn't work quite like Emacs (which the docs imply it does). As for the rest, I suppose we'll have to agree to disagree partially. There's plenty of value in having the information on a web site. I often browse docs when I'm not at my computer. Thanks. On Thu, Oct 11, 2018 at 2:18 AM Edward K. Ream <[email protected]> wrote: > On Wednesday, October 10, 2018 at 6:01:29 PM UTC-5, [email protected] > wrote: >> >> Below are some random examples. >> > > A few comments. > > Will any command I create that manipulates texts/nodes automatically be >> undo-able? >> > > No. Imo, there is no way to do this automatically. > > If not, what do I need to do to ensure it is? >> > > You have to insert calls to u.beforeSomething and u.afterSomething, where > u is c.undoer and "Something" is one of a list of possible actions. The > complete list is in leoUndo.py. In essence, the "before" method saves the > *relevant* data before executing the command, and the "after" method > saves the corresponding data after executing the command. Saving only part > of the outline's data is an absolutely essential optimization. > > There have been proposals by smart people to make undoing simpler. I have > never been convinced those proposals were sound. > > >> 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. >> > > On the contrary, the list documents the *existence *of a feature or > method. That's a big hint. > > If all these classes/functions had good docstrings, one could autogenerate >> the docs using a script. >> > > Sure, but where would you put these docs, and who would read them? I > repeat, leoPy.leo (LeoPyRef.leo) is your friend. > > What is an ivar? >> > > An instance variable, that is, a variable defined in a class. This is > pretty common terminology, but I'll make sure it is defined in the > tutorials and CheatSheet.leo. > > I could not get unit testing to work in a way that is useful for me (see >> my other email on the mailing list). >> > > Sorry about the delay in responding. I have been overwhelmed with work > lately, in a good way. > > 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. >> > > Specific suggestions for improvements are welcome. General comments, not > so much. > > The commands reference page mentions macros. Do they work? >> > > Macros have been removed. Leo's scripting is much more powerful. > > 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. >> > > #337 <https://github.com/leo-editor/leo-editor/issues/337> deals with > this. > > How do I comment and uncomment multiple lines? >> > > Select the lines (anywhere in the first and last lines will do) and > execute add-comments, Ctrl-[. Similarly, delete-comments, Ctrl-] removes > comments. > > >> Is that documented? >> > > Yes, in LeoDocs.leo, and on the corresponding web page. I'll improve the > docs. > > 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? >> > > Not very much. leoSettings.leo *is* the documentation for settings. > That's the point of having Leo around. > > There are general comments about settings in the Customizing Leo > <http://leoeditor.com/customizing.html> chapter. > > I'd like a page that lists all the settings, with descriptions. >> > > Why in the world would I want to do that? > > Many @settings nodes have descriptions, and many others do not, so I have >> little idea as to what they do. >> > > That's a legitimate complaint, especially since one needs a regex to find > the setting. That is, the code might use either '_' or '-' as > separators. This really should be fixed, say by picking '-' as the > recommended separator within leoSettings.leo and the code itself. I have > just created #993 <https://github.com/leo-editor/leo-editor/issues/993> > for this. > > Part of the documentation effort should be to put a good description of >> each one. Is Leo "aware" of all its settings? >> > > Only the code that uses a setting is aware of the setting. Leo's > configuration code is aware of the *kinds *of settings that can appear in > an @settings tree, but settings themselves are completely dynamic. There > is no master list of settings. > > You can add a setting in *any* @settings tree, including a local .leo > file, and scripts can access that setting after reloading Leo, or after the > reload-settings command. > > 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. >> > > They do have a "page". It's leoSettings.leo. You can open it with the > leo-settings-leo command. > > And sure, you could create such a script, and you could even create a > hierarchical set of pages with Leo's rst3 command (@rst nodes). > > 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. >> > > See @button check-settings in leoSettings.leo. Cleaning these settings > would be a big project. > > I don't remember whether the present script "canonicalizes" settings names > (converts '_' to '-', but I suspect not.) So #993 should be done first. > > We have various directives. Can I create my own? >> > > Yes. > > This may well be documented, but I don't know if it is. >> > > Only in the code ;-) g.globalDirectiveList is a mutable list. Plugins > (or even scripts) can add to this at any time. It's an advanced feature, > but it would be useful when defining decorators. > > >> 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. >> > > Sure, but I'm not going to revisit every single function. Let me know > which ones you want documented. > > Short names are sometimes controversial, but imo if you can't remember c, > g, and p you should not be writing Leo scripts. Make *sure* you memorize > everything in the "about this file" node in leoPy.leo, including all its > sub-nodes. All of it should be in the cheat sheet. I've just made a > private note to myself about this. It will happen soon. > > >> 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? >> > > Good question. The source code won't help much. Instead, you have to > create a new myLanguage.py file in the leo/modes folder. There is a script > to convert a jEdit myLanguage.xml file into the corresponding myLanguage.py > file. It's in scripts.leo. Open it with the leo-scripts-leo command. > Search for "jedit" and you will find @button jEdit2Py. > > In essence, you have to understand the jEdit xml conventions, or infer > them from the files in leo/modes. This is an advanced topic, and iirc you > are the first to ask about it. The corresponding code in leoColorizer.py > is highly optimized, and therefore not simple. > > Are all the default keybindings documented? >> > > Only in leoSettings.leo. Look for the top-level node called "Keyboard > shortcuts". > > 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. >> > > I don't fully agree with this statement. Remember that Leo arose because > typical "flat" documentation can often be difficult to use and understand. > Hierarchical organization, combined with searching, is often more useful. > That's why I keep referring people to the actual .leo files. > > Newbies only need to know how to search outlines, and which outlines to > search, especially LeoDocs.leo, leoSettings.leo and CheatSheet.leo. > Really, how hard is it to scan the top-level nodes in leoSettings.leo? > > 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. > -- 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.
