Let me open with I hope my writings won't offend. These are my experiences and frustrations. I do really like working with Leo because it helps me organize things better but I am frustrated working with Leo because it hurts my hands and I really want to make it work with speech recognition but I haven't been able to figure out how to yet. ----- Holy cow, I've been trying to do way too many things with Leo. I've been trying to adapt my thinking to the Leo way of programming, give up my preconceptions about literate programming from working with cweb, I'm trying to understand how to write a plug-in so I can do my speech-enabled programming environment and I'm trying to get real work done in Leo so I can get paid.
I apologize for the random nature of these questions for if I had had more time, they would've been shorter and better organized not to mention fixing speech recognition errors. why are doc strings preferred to@doc/@code pairing? Back when I used cweb, I really like the ability produce a document that was also executable. Leo, doesn't really do that. The natural path of working with Leo seems to be quite different. The hierarchy is incredibly useful, the ability to gather up small scope sections of code into something you can execute is wonderful but from a writing standpoint, it's not really literate programming. 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. 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. 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. 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. 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. Day-to-day, I use maybe a half a dozen commands in Leo. 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. Yeah I was actually adjusting indentation by adding and removing spaces on every line because I couldn't find the command. I'm sure there are other commands there that would be really helpful to me but the menu organization is by command type, not task you're trying to accomplish. To be fair, I think the problem is that you're trying to cram a command space which is more suited to a speech interface into a GUI environment. Speech interfaces tend to have a lot of commands (wide) but not many secondary commands underneath the main command (shallow). In contrast, the GUI environment has very few top-level items and lots and lots of commands underneath to a great depth. 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. 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 and hopefully can get some help figuring out which Leo commands already exist or can be aggregated into the kind of command I need. Along that line, I think having a task oriented interface would be really helpful to help people climb the Leo learning curve. I know I can design the interface but I have no idea how to get there. Example of a command I need for speech interface is the Emacs mark and point. There is no way in hell I'm going to click and drag the mouse with a speech command. *It just does not work*. 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. 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. While having commands that identify and select regions are clearly essential for speech interface, I believe that similar commands for keyboards would also be a huge win over the current navigate by character/line 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 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. The only reason I would even consider migrating back to Emacs is that I've already climbed the learning curve, it has the basics I need so I can stumble along with speech and I'm willing to accept that, given my disability, it may be the best I can do even though Leo has a much larger win if I could just get past that initial hurdle. 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. I put together a few things that work for me but have no idea it would be useful to other people. For example on my bottle apps, I have sections for the bottle environment, another section for modules that are used in the app but are not directly related to managing bottle, sections for the Apache configuration, the installer and then notes about what I'm doing. 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. Couple more thoughts on surface area. 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. It feels like I need to know everything about leo before I can understand anything. I have been trying to take what commands I do use and put them into speech commands. 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. From reading the documentation, I think I can do that but I'm not sure how to make that happen and with the coding I am doing, my hands are hurting enough I don't have a lot of energy to explore by trying. 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. 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. Thank you for reading. --- eric -- 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.
