I want to be very clear about one thing. What I wrote was not a complaint. It was an expression of information overload. I am very enthusiastic about Leo, I'm just frustrated My disability keeps me from climbing over some of the necessary terrain.
On Wednesday, May 24, 2017 at 12:51:33 PM UTC-4, Edward K. Ream wrote: > > On Wed, May 24, 2017 at 9:25 AM, Eric S. Johansson <[email protected] > <javascript:>> 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 :-) > Okay that's a fair return. :-) > > > >> 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." > There are two types of structure. One is the structure of code in hierarchy and organization of entities, another is the hierarchy expressed in Leo. But in writing there is the structure of the narrative, the plot line of characters. To be fair, the narrative structure of writing doesn't map well to code but does map well to explaining an API/object. Another way of thinking of it is that the narrative is better explaining what it does, not how it does it. On the third hand, being able to insert images and diagrams into code would be really useful. > > 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. > > I think we using two different definitions of definition in the body of the text. What I'm looking for is: c, g and p. <http://leoeditor.com/tutorial-scripting.html#predefined-symbols-c-g-and-p> When you initially introduce the use of cg and p in a section, you put in a link to the definition. Although the definition didn't really help me much because I didn't know what a commander is. Another example: g is Leo’s leo.core.leoGlobals <http://#!> containing many useful functions, including g.es. <https://leoeditor.com> 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. > I understand. I felt the note was going long enough that putting in detail would distract from other points. For me the the way I would want information about Leo plug-ins is this: 1. How do I access the contents of the node? 2. How do I change the contents of a node? 3. How do I store context dependent information for later use? 4. How do I invoke my code on an event such as doing something before or after saving? 5. How do I tell Leo to save the results of my code interpreting the contents of the node rather than the contents of a node And yes, I would be glad to work with Louis Neil on improving documentation. > > >> 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. > > There is always a map. It may not be regular it may be messy and organic like the natural landscape but there is always a map. > > 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. > And this may be a path for documentation. There are core concepts such as c, g, and p that deserve more detailed treatment of what they are and how they work. Then there are groups of commands that work together that should be explained as a separate story. > > >> 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. > I hope you understand why that's not really a good solution for speech recognition. :-) ... *Leave Mark* *jump to end of block* *indent region* Or, a better form would be: *Indent block* I'll explain what I mean by block in a different note. 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. > Will do > > > >> 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. > Done. I also added a second enhancement request for having a series of commands "<jump|push> to <beginning | start | finish | end> of line". I'll elaborate more later also having a "push here" as a way of remembering the current location would also be useful. Yes yes, my first calculator was HP 45 and I really liked using forth. > > > >> 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) > Okay I will follow up on that later. > > 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. > Ime, If the guideline is a page or two long, it helps a lot. Voluminous documentation just doesn't work. I cannot tell you the number of old-school manuals from Digital Equipment or IBM That were better used as book stops by my peers and myself. > > 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. > Okay, I will look at that > > > 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. > Here's what has been working well for me: 1. @file server/CollectServer.py 1. imports 1. << adjust paths >> 2. Bottle 1. << main >> 2. << bottle hook before request >> 3. << route: collect >> 4. << route: static file >> 5. << route: data log >> 3. Utility 1. << construct register response >> 2. flip settings 3. zone_generator 4. wsgi init 2. @file test/test_device_push.py 1. imports 2. test code 3. Deploy/config 1. @clean installCollectServer.sh 2. @clean config/CollectServer.conf > 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. > I'm reasonably close to the expectations you just set out. Are you familiar with the learning technique of explaining what you learned to a novice? That if you have a system and can't explain it to a college freshman, you really don't understand the problem yet. That wisdom came from Dr. Feynman. > > > 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. > Thank you for saying that. I apologize for it being so long because I really didn't have time to write a short one. We all have blind spots. Working with others and listening to them is the best way I've found at reducing my blind spots. thank you for listening and reading. > -- 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.
