On Wed, May 24, 2017 at 9:25 AM, Eric S. Johansson <[email protected]> wrote:
why are doc strings preferred to@doc/@code pairing > ? > Because docstrings are preferred to comments in python. > Back when I used cweb, I really like the ability produce a document that > was also executable. Leo, doesn't really do that. > That's news to me :-) > it's not really literate programming. > I agree. Imo, Leo redefines LP. As I write in the history of Leo <http://leoeditor.com/history.html#beginnings>, "Late in 1997 I wrote a Print command to typeset an outline. Printing (Weaving) is supposedly a key feature of literate programming. Imagine my surprise when I realized that such a “beautiful” program listing was almost unintelligible; all the structure inherent in the outline was lost! I saw clearly that typesetting, no matter how well done, is no substitute for explicit structure." The process of getting started with writing scripts/plug-ins is, to me > quite overwhelming because there is a huge surface area and I think the api > documentation could be better conveyed by inverting the way it is > expressed. > I don't understand what you mean. > Also, some redundancy would be helpful. For example, if you read the > writing plug-in section, you find the statement *Plugins do not have > automatic access to c, g and p.* And even though I have been reading the > documentation and I knew about c, g, and p, in that moment I had no idea > what they meant or where to find them. > It's hopeless to redefine c, g and p everywhere. You are just going to have to learn what they mean. > I went back and reread the first section looking for clues and found *Writing > plugins is like writing any other Leo script. See Scripting Leo with > Python. In particular: *and that is where I found: *Three predefined > symbols, c, g and p give Leo scripts easy access to all the data in the > outline. These symbols also allow Leo scripts to execute any code in Leo’s > own code base* which told me enough to keep reading the plug-ins document > but not enough to do anything with it. Putting that short description in > the plug-ins document would've allowed for uninterrupted reading. > Except that the definitions interrupt the reading. Coming back to what I meant by inverting the way it is expressed, don't > tell the developer what they can do, start from their perspective and help > them find what they need to do to solve their problem. Guide them in terms > of what are the common models of accessing information within a Leo > environment. > General complaints are much less helpful than specific suggestions. Lewis Neal has done a great job of small but incredibly useful improvements. Perhaps you two could work together. > From my trying to learn Leo, the impression I have is that > command/operations are either restricted in scope to a single node or deal > with a hierarchy of information from a given node. When do you choose? Are > there more models for accessing information within Leo? I don't need to > know the details (just yet). I need to know the terrain, the higher level > map before I can orient myself enough to understand and make sense of the > detail. > The map doesn't exist. Commands do what they do, based on what they are trying to do. Some commands toggle settings. Others print messages. Others alter the tree. Others traverse the tree. Day-to-day, I use maybe a half a dozen commands in Leo. > Good idea. Don't try to learn everything. Neither Terry nor myself knows all the details. > Mostly it's to navigate and create nodes within the hierarchy. To be > honest, it took me a while before I figured out where the command to > indent/out dent code was located > . > Select the lines, then do Tab or Shift-Tab. > Think about the number of times you click on a top menu bar item then he > hit a submenu which is another submenu which brings up a dialog box with > tabs. That's a deep interface and also one is really difficult to discover. > I almost never use menus. Imo, they are just a form of documentation. If you think it would be a benefit, I would take the time to write down the > kind of commands I need day-to-day for programming > Please do that. They all belong in Leo's cheat sheet. > Example of a command I need for speech interface is the Emacs mark and > point. > You can do this with shift arrow keys, but that may not be easy for you. I use Ctrl-Home and Ctrl-End all the time. They greatly reduce my use of the mouse. But with speech, I can say "leave Mark" and then move the mouse to > someplace else and speak a command that operates on a region. > Please file an enhancement request. Leo already has an exchange-point-mark command, but it's probably only part of the solution. > Note: It's important to remember that a good speech interface selects or > operates on a region. Most people are familiar with commands that operate > on a region. What's not common is commands that select a region. For > example a command "select last sentence" turns last sentence into a region. > Emacs has the simplest version of this which is things like select word, > line, sentence, paragraph etc. > Leo has similar commands. If I was to try and implement a mark and point method of selecting a > region, I would have no idea where to begin > Begin by studying LeoPy.leo: Code-->Command classes--> @file ../commands/editCommands.py--> class EditCommandsClass-->move cursor... (leoEditCommands) and the amount of what I need to understand in order to implement this > would be discouraging enough that I probably wouldn't try and would > eventually migrate back to Emacs. > Just file an enhancement request. I can write and test the code in an hour. > In general however for programmers of any physical ability, I think would > be really helpful to have a "best practices" guide for writing code in Leo. > Imo, nobody gets much out of documentation. Instead, it's much easier to study code in Leo outlines. I can say this after spending a month wrestling with the npyscreen code. I imported the code in to Leo, and after that I just read the code. The cff command is an amazing tool for comprehension. Use it, and stop worrying about docs. > When I import Python code from another developer it looks like you have a > rough form of a best practices encoded in the importer code but it did some > things that I didn't expect but they make sense so I'm going back over my > code to see what I can change to match what your import did. > I wouldn't be so quick to do that. leoPy.leo, not imported code, contains my version of best practices. They are easily stated: use separate nodes for classes, functions and methods. Importers don't always follow my preferred style because of technical issues. In particular, I always use sections for lengthy lists of python import statements, but importers don't do that. *Important*: In my early days of Leo, I broke lengthy code into sections, using section references instead of functions. Today, I despise that style. Using sections for programming is a truly bad idea. *Never* do that in new code. The exception is for languages like html and markdown that have no functions or classes. When I try to find out what any command does, there is so much shorthand > that it takes a long time for me to figure out what I need to know. > Start with the basics. Write a script that uses c, g and p. After that, you just have to read, read, read what's already there. Start with the cheat sheet, then the various tutorials. *Expect to read everything 2 to 10 times*. Don't assume complex things can be made easy. You have to do the work. Many have. Many haven't. > My preference would be something like the Emacs *M-x some-command* interface > because it's easier to work with in my speech toolkit than keyboard > shortcuts. > In Leo, we spell it <Alt-x> some-command. Leo has stolen all useful features from Emacs... > That last point is really important one for people with working hands to > understand. For most of us with a programming triggered hand injury, we > have to be very careful where we use our hands because it's a limited > resource. > My left thumb is chronically sore. Using Ctrl-Home/End has made a great difference. I can well imaging that you are having more difficulties than I. I welcome any suggestions you might have for reducing hand strain. > I could say more but the important thing to take away is how design > decisions you make, not just in Leo but in any software, runs the risk of > isolating someone that doesn't have full physical abilities. > I'm glad you wrote this long letter. Surely I do have some blind spots regarding commands and key combinations. Any suggestions you have will help us both. 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.
