Climbing the learning curve and other things I'm puzzled about

[Eric S. Johansson]

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

[Zoom.Quiet]

On Wed, May 24, 2017 at 9:25 AM, Eric S. Johansson
<ynotla...@gmail.com> wrote:
...

> 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

Hum.... never try tab ?
as others editor, Leo just only so less action not same with others,

> 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.

that is true, i agree all,
but in my feel, Leo make most editor action very same others,
of course, i am only pure user, not Leo develop,
never try develop some plugins for enhanced Leo, because the original
functions, is already very strong support me all kinds of develop
working

--
life is pathetic, go Pythonic! 人生苦短, Python当歌!
俺: http://zoomquiet.io
授: http://creativecommons.org/licenses/by-sa/2.5/cn/
怒: 冗余不做,日子甭过!备份不做,十恶不赦!
KM keep growing environment culture which promoting organization learning!

[Edward K. Ream]

On Wed, May 24, 2017 at 9:25 AM, Eric S. Johansson <ynotla...@gmail.com> 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, ​

 

​"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

[Terry Brown]

On Wed, 24 May 2017 11:51:31 -0500
"Edward K. Ream" <edre...@gmail.com> wrote:

> On Wed, May 24, 2017 at 9:25 AM, Eric S. Johansson
> <ynotla...@gmail.com> 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, ​ 

My impression is that literate programming in the sense of mixing docs.
and code has really fallen out of favor for things like software, but
is very popular for analysis exercises, as in R-markdown with knitr
and also Jupyter notebooks. In these cases it's not just
docs / code / docs / code / docs ... but
docs / code / table / docs / code / plot / ...

I'm actually fiddling with this project:
https://github.com/tbnorth/pypanart which tries to get a Python only (no R) pipeline
to producing manuscripts from markdown - it seems to me that Jupyter
stops short of manuscripts, stopping at the internal report stage, but
maybe I just don't know it well enough.

Note that my project and the R pipeline and maybe Jupyter, don't know,
all rely on pandoc.

Cheers -Terry

[Eric S. Johansson]

On Wednesday, May 24, 2017 at 2:13:17 PM UTC-4, Terry Brown wrote:

My impression is that literate programming in the sense of mixing docs.
and code has really fallen out of favor for things like software, but
is very popular for analysis exercises, as in R-markdown with knitr
and also Jupyter notebooks.  In these cases it's not just
docs / code / docs / code / docs ... but
docs / code / table / docs / code / plot / ...

I would argue, it has fallen out of favor because explaining things is hard. It's part writing ability and part information presentation. I would go as far as saying that either of those two is much harder than code. Personally, I would be happy if I could find a way to produce API documentation and examples interwoven with the actual implementation. In this model weaving would produce just the API doc, not the entire "story" created by the code. The reason I want them together is because if I change the API, I want the documentation right there so I can bring it up to date without having to go find it somewhere else.

I'm actually fiddling with this project:
https://github.com/tbnorth/pypanart which tries to get a Python only (no R) pipeline

...

That looks quite intriguing. Although I will thank you for the indirect reference to doit. That will be more useful to me in the short term ;-)

[Eric S. Johansson]

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 <ynotla...@gmail.com> 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, ​

 

​"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.

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 containing many useful functions, including g.es.

By adding links at the appropriate place, you can enhance the ability of a reader to find the information they need. Yes interrupts the reading flow but it puts at their fingertips rather than forcing them to search or remember where it was located.

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.

[Offray Vladimir Luna Cárdenas]

Hi,

On 24/05/17 13:13, Terry Brown wrote:
> On Wed, 24 May 2017 11:51:31 -0500
> "Edward K. Ream" <edre...@gmail.com> wrote:
>
>> On Wed, May 24, 2017 at 9:25 AM, Eric S. Johansson
>> <ynotla...@gmail.com> 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, ​
> My impression is that literate programming in the sense of mixing docs.
> and code has really fallen out of favor for things like software, but
> is very popular for analysis exercises, as in R-markdown with knitr
> and also Jupyter notebooks. In these cases it's not just
> docs / code / docs / code / docs ... but
> docs / code / table / docs / code / plot / ...

Jupyter people define this intertwining process as Literate Computing
[1][2]. I think that it opens the door of computing to a lot of people
beyond programmers (scientists, journalist, activists, writers, etc),
and as it has been discussed before, Leo in this kind of context could
be pretty powerful and increase its user base, but that would require
support for a way of interactive computation (a la IPython, or Org
Mode), but is still a path with many things to explore/implement. My
exploration of such ideas in a Pharo/Smalltalk environment is done via
Grafoscopio [3]

[1] http://blog.fperez.org/2013/04/literate-computing-and-computational.html
[2]
https://www.reddit.com/r/IPython/comments/556nnt/do_jupyter_notebooks_promote_literate_programming/
[3] http://mutabit.com/grafoscopio/index.en.html

Cheers,

Offray

[Edward K. Ream]

On Wed, May 24, 2017 at 2:53 PM, Eric S. Johansson <ynotla...@gmail.com> wrote:

> 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.

There

​

​have been lengthy, ​

ongoing discussions about

​ the​

difficulties of using, say, the rst3 command, to document code. 

​N​

either clones nor bookmarks suffice to "access" code, comments or any other "narrative item" 

​embedded​

​

a Leo outline.

The general solution is a custom script that "pick

​s​

out" the desired data,

​

​creating either ​

an @rst tree or, say, an @auto-md tree. What

​

​gets ​

"pick

​ed​

out" from an outline requires some kind of additional markup that you (your script) supplies.

>

​ ​

What I'm looking for is [links to definitions].

Yes, that would be useful, in specific places.

> For me the the way I would want information about Leo plug-ins is this:
> How do I access the contents of the node?
> How do I change the contents of a node?
> How do I store context dependent information for later use?

These are all basic operations on p.  p.h is the headline, p.b is the body text. p.u is the user attributes (uA).

>

​ ​

How do I invoke my code on an event such as doing something before or after saving?

Define event handlers, as described

​​

here, in the

​​

writing plugins chapter.

> 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

I don't understand this question.

>>

​ ​

Select the lines, then do Tab or Shift-Tab.

>

​ ​

I hope you understand why that's not really a good solution for speech recognition. :-) ...

Actually, I don't understand.

>

​ ​

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.

Leo already can do almost all of this. For specific tweaks you could define @commands.

>

​ ​

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.

You can probably do this in Leo.

>

​ ​

I also added a second enhancement request for having a series of commands "<jump|push> to <beginning | start | finish | end> of line".

How do you think Leo implements Ctrl-Home and Ctrl-End? These bindings aren't built into Leo! Instead, there are commands that are bound to Ctrl-Home, Ctrl-End and many other sequences.

Here's how to find them.  Do a regex search for ctrl.home in leoSettings.leo  You will find:

beginning-of-buffer = Ctrl-Home

This is in a node called (not very helpfully) Changes.  The parent is
@keys EKR bindings.  Look in 

these ​

nodes:

@shortcuts Arrow keys and the <return> key
@shortcuts Changes
@shortcuts Cursor Moves

You will see that Leo already has

​​

all the standard Emacs commands related to cursor movement, with the possible exception of the Emacs mark command.  But don't be so sure about that.  Leo knows the about selections, and the direction of selections (point and mark).

>

​ ​

If the guideline is a page or two long, it helps a lot. Voluminous documentation just doesn't work.

Leo has several summaries.  Start with the cheat sheet.

​​

> Are you familiar with the learning technique of explaining what you learned to a novice?

I explain things to Rebecca :-)

​> I apologize for it being so long because I really didn't have time to write a short one.

Lack of time is a feeble excuse.​

Edward
------------------------------------------------------------------------------------------
Edward K. Ream: edre...@gmail.com Leo: http://leoeditor.com/
------------------------------------------------------------------------------------------

[Eric S. Johansson]

On Thursday, May 25, 2017 at 6:21:30 AM UTC-4, Edward K. Ream wrote:

On Wed, May 24, 2017 at 2:53 PM, Eric S. Johansson <ynotla...@gmail.com> wrote:

> 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.

There

​

​have been lengthy, ​

ongoing discussions about

​ the​

difficulties of using, say, the rst3 command, to document code. 

​N​

either clones nor bookmarks suffice to "access" code, comments or any other "narrative item" 

​embedded​

​

a Leo outline.

The general solution is a custom script that "pick

​s​

out" the desired data,

​

​creating either ​

an @rst tree or, say, an @auto-md tree. What

​

​gets ​

"pick

​ed​

out" from an outline requires some kind of additional markup that you (your script) supplies.

The last paragraph is close to what I'm looking for. For example, from my sajax module for brython, I would want to see something like"

  def request(self, Ajax_URL, Ajax_mode ="GET", arg_dict=None):

• Ajax_URL = string containing URL used for the GET or POST request
  
• Ajax_mode = request type. Supported modes are GET and POST
  
• arg_dict = is a dictionary containing arguments to be passed to the server. Arguments will be formatted according to the mode
  

The request method of class sajax triggers request via the URL and mode given. The two supported modes are GET and POST. Any data passed from the browser to the server is held in arg_dict. The contents of arg_dict are formatted into a URL encoded string appended to the URL for GET requests and properly formatted and embedded in the body of a POST request.

----

While it's entirely possible for this documentation to be embedded in code, I would rather see it directed to a separate document for human consumption. I "should" be able to link to the definition of the method so that I don't have to cut and paste the information and run the risk of getting out of sync. In Leo terminology, it is a clone although not of an entire node. As an after thought, it would be nice to be able to include things like drawings in the documentation which is another reason why should be separate from the code.

>

​ ​

What I'm looking for is [links to definitions].

Yes, that would be useful, in specific places.

I will try to identify and record such places as issues 

> For me the the way I would want information about Leo plug-ins is this:
> How do I access the contents of the node?
> How do I change the contents of a node?
> How do I store context dependent information for later use?

These are all basic operations on p.  p.h is the headline, p.b is the body text. p.u is the user attributes (uA).

>

​ ​

How do I invoke my code on an event such as doing something before or after saving?

Define event handlers, as described

​​

here, in the

​​

writing plugins chapter.

> 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

I don't understand this question.

For example, let's say I have user attribute set like

uA["color"]="red"
uA["car"]="ford"
uA["wheel"]="round"

and the body was:

On my $color $car, I have $wheel wheels

When I save, the body and user attributes would be preserved somewhere but the file, as specified by some @xxx command would contain:

On my red car, I have round wheels

In other words, I have a template I have values, and I want to save result of processing the template. Now there may be other computational efforts I may use to create the final output but it is basically what I have described. I have seen a plug-in that looks similar to this but I haven't explored all of his capabilities yet. I wasn't fond of the markup indicator "left brace space bar left brace" then "right brace space bar right brace"

This is should be useful in programming by speech. Defining a template and then filling in the blanks is more effective than straight dictation of code especially if I use the template more than once.

Let's save for another discussion is the idea of templates being cloned with individual uA sections.

 

>>

​ ​

Select the lines, then do Tab or Shift-Tab.

>

​ ​

I hope you understand why that's not really a good solution for speech recognition. :-) ...

Actually, I don't understand.

I could create a speech macro that would emit a tab or shift tab when I say indent or out dent region. Done that before works okay but what if I want to parameterize and say indent this block or out dent five lines. Then the problem becomes a little more difficult to implement with simple keystrokes.

With an API like interface, I could run a selection routine counting by lines or by features in the code and and then run the indentation command.

The one thing I don't ever want to do is "speak the keyboard" where you say individual letters or command keys to make something happen. It's a horrible thing to do to your voice 

>

​ ​

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.

Leo already can do almost all of this. For specific tweaks you could define @commands.

>

​ ​

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.

You can probably do this in Leo.

>

​ ​

I also added a second enhancement request for having a series of commands "<jump|push> to <beginning | start | finish | end> of line".

How do you think Leo implements Ctrl-Home and Ctrl-End? These bindings aren't built into Leo! Instead, there are commands that are bound to Ctrl-Home, Ctrl-End and many other sequences.

Here's how to find them.  Do a regex search for ctrl.home in leoSettings.leo  You will find:

beginning-of-buffer = Ctrl-Home

This is in a node called (not very helpfully) Changes.  The parent is
@keys EKR bindings.  Look in 

these ​

nodes:

@shortcuts Arrow keys and the <return> key
@shortcuts Changes
@shortcuts Cursor Moves

You will see that Leo already has

​​

all the standard Emacs commands related to cursor movement, with the possible exception of the Emacs mark command.  But don't be so sure about that.  Leo knows the about selections, and the direction of selections (point and mark).

Okay I will do more reading and get back to you with questions

 

>

​ ​

If the guideline is a page or two long, it helps a lot. Voluminous documentation just doesn't work.

Leo has several summaries.  Start with the cheat sheet.

​​

> Are you familiar with the learning technique of explaining what you learned to a novice?

I explain things to Rebecca :-)

That could work. :-) 

​> I apologize for it being so long because I really didn't have time to write a short one.

Lack of time is a feeble excuse.​

Yes it is but it is also reference to a well-known (mis)quote and a self-deprecating joke all in one. 

http://quoteinvestigator.com/2012/04/28/shorter-letter/

[Edward K. Ream]

​On Thu, May 25, 2017 at 5:19 PM, Eric S. Johansson <ynotla...@gmail.com> wrote:

>  How do I tell Leo to  save the result​​s of my code interpreting the contents of the node rather than the contents of a node​?

My bad.​ ​The question seems straightforward as I read it again.  As you say, you can use uA's, or you can, by convention, place the results in another node.  You could create an @results tree, for example.

> I could create a speech macro that would emit a tab or shift tab when I say indent or out dent region. Done that before works okay but what if I want to parameterize and say indent this block or out dent five lines.

​The challenge would seem to be supplying arguments. You should be able to write macros of any complexity using @command. The details may depend on your speech recognition system. Feel free to ask more questions.

Edward