PyOhio Talk

[tfer]

I'm putting together a proposal for a talk on Leo at the PyOhio conference in Columbus, July 28th & 29th.  If accepted, it should give us an introductory video as these talks are normally taped.

I'm titling the talk: Leo: a paradigm shifting IDE

The description (400 character limit) of which I'm giving as:
Leo is an open source IDE coded in python, using PyQt. It can be used as a general project manager, handling all the files in your project, no matter what language(s), you are writing in. The shift that Leo gives you is that can organize your projects formally below the file level, which previously could only be done informally with section comments. Using outlines supports thinking & organizing.

Proposal deadline is June 1st, it can be edited until then.

I need to do a talk abstract.

Talks are 40 minutes.

Suggestions for material and wording can be discussed here.

Tom

[Edward K. Ream]

On Wed, May 23, 2012 at 6:29 PM, tfer <tfeth...@aol.com> wrote:

> I'm putting together a proposal for a talk on Leo at the PyOhio conference in Columbus, July 28th & 29th.  If accepted, it should give us an introductory video as these talks are normally taped.

That's great news. Thanks very much for this.

Edward

[tfer]

Here is what I've got for the abstract of the talk:

Leo is an outliner, each node in a leo outline has two parts, a headline - a single line topic, and its body text, either of which can be blank.  Headlines are displayed in the "outline pane" their position and indent level give a visual representation of the outlines hierarchical tree structure.  Whenever a headline is selected in the outline pane, its body text will be visible in the body pane.  The files in your project head up their own subtree in the outline, the root of each has a special headline that names the file to create/update from the body text of its descendants.  A template, usually in the body text of that special headline, determines how the body text in each descendent will be gathered up to generate the named file on each save.  Using this system allows you to lay out and organize your different areas of functionality your code will implement, then write code, or write code and then organize, or mix this up however you are drawn to do.  Rearranging code is easy, just move the headlines around and the code in the associated body text is moved too.

Commenting code in body text is cheap and easy, by default text entered into a body starts a free form, wrapped comment, when you want to start your code, just put the "code-start", (@c -- short for @code) directive on a new line, then write your code below it.  However, there is another, implicit type of commenting available through the headlines, just give the headline a short sentence about what your up to in that nodes descendents.  You can use this to quickly capture what you intend you code to do, and then come back later and write the code.

The ability of outlines to capture, but then hide details to allow you to shift your focus to another area of the system is one of Leo great strengths.

[Edward K. Ream]

On Fri, May 25, 2012 at 8:01 PM, tfer <tfeth...@aol.com> wrote:
> Here is what I've got for the abstract of the talk:

Hi Tom,

Imo, the abstract should attempt to convey why you think Leo is a
paradigm shift. Stress what is unique in Leo, and essentially nothing
else.

> Leo is an outliner, each node in a leo outline has two parts, a headline - a
> single line topic, and its body text, either of which can be blank.
> Headlines are displayed in the "outline pane" their position and indent
> level give a visual representation of the outlines hierarchical tree
> structure.  Whenever a headline is selected in the outline pane, its body
> text will be visible in the body pane.

So far, Leo sounds utterly unremarkable. You might consider deleting,
or drastically shortening it.

Something like, "Leo looks like a typical outlining program. However, ..."

> The files in your project head up
> their own subtree in the outline, the root of each has a special headline
> that names the file to create/update from the body text of its descendants.
> A template, usually in the body text of that special headline, determines
> how the body text in each descendent will be gathered up to generate the
> named file on each save.

I like your use of the term "template". It's evocative, and allows
you to avoid details about @others and sections. In fact, any node can
contain a template, in the sense you mean it.

I also like that you didn't discuss @file nodes explicitly. You might
shorten the description still further by saying something like:
"designated parts of Leo outlines can correspond to external text
files."

> Using this system allows you to lay out and
> organize your different areas of functionality your code will implement,
> then write code, or write code and then organize, or mix this up however you
> are drawn to do.  Rearranging code is easy, just move the headlines around
> and the code in the associated body text is moved too.

Not bad. I might be shorter.

> Commenting code in body text is cheap and easy, by default text entered into
> a body starts a free form, wrapped comment, when you want to start your
> code, just put the "code-start", (@c -- short for @code) directive on a new
> line, then write your code below it.  However, there is another, implicit
> type of commenting available through the headlines, just give the headline a
> short sentence about what your up to in that nodes descendents.  You can use
> this to quickly capture what you intend you code to do, and then come back
> later and write the code.

I would delete this from the abstract, and probably from the talk. It
is a relatively unimportant.

> The ability of outlines to capture, but then hide details to allow you to
> shift your focus to another area of the system is one of Leo great
> strengths.

Yes.

There are at least four unique aspects of Leo you haven't mentioned:

1. The two-way correspondence between external files and Leo outlines.

2. uA's extend what each node may contain.

3. Leo's dead-simple Python DOM: iterators, p.b, p.h, p.v and p.v.u.

4. @button and plugins.

HTH.

Edward

[Edward K. Ream]

On May 26, 4:27 am, "Edward K. Ream" <edream...@gmail.com> wrote:

> I like your use of the term "template".  It's evocative, and allows you to avoid details about @others and sections.

The term "template" is brilliant. Rather than saying something overly
general, as I have been saying for years, "in Leo, outlines are
significant everywhere", the term allows us to say something like:

"In Leo, templates are aware of outline structure and, thanks to Leo's
DOM, Leo scripts are aware of the outline in which they are embedded."

External files created by Leo are *not* aware of outline structure,
unless they use the leoBridge module. Thus the distinction between
Leo scripts (including plugins) and external files becomes sharper:
the former are aware of outline structure, the latter are not.

Here, the template language consists of @others, sections and section
references, and Leo directives. All three "understand" outline
structure, and are defined in terms of outline structure. Also, the
term "outline structure" really refers to *graph* (DAG) structure.

It may be too late to change your abstract, but I hope this helps
organize your talk. It has certainly clarified my thinking.

Edward

[tfer]

No I can revise the abstract until the first of June, I like all this comments and will incorporate them.  Looking at what I have make it seem like more of the actual talk and less of an abstract.

Tom

[tfer]

Even rougher second draft:
Special headlines can be used to designated parts of Leo outlines that correspond to external text
files.  Such headlines can have files generated from their subtrees by template(s) contained in body text. These templates determine how the file will be assembled from the descendent nodes.  Alternatively, other forms of these headlines can read in entire files and dissect them into outlines.

One of the big ideas of Leo is that the body text in nodes is data, an analogy can be made to the cells in spreadsheets, here the data is not in a grid, but held in graphs, each node having a parent, possible siblings, and descendents. Leo has a dead simple DOM held in the python data structures that is easily interacted with via python.  All sorts of transforms, summarizing, and synthesizing are doable via python.

More than just text can be held in a node, Leo has a way to add whatever you like via, what are called, "unknown attributes", or uA's.  These are unknown in the sense that Leo is set up to deal with text, but through through detectors  uA's are found, made to persist, and, via custom or plug-in coding dealt with.

1. There is a two-way correspondence between external files and Leo outlines.

2. uA's extend what each node may contain.

3. Leo's dead-simple Python DOM:  iterators, p.b, p.h, p.v and p.v.u.

4. @button provide clickable, entered on the fly, scripts that takes you far beyond any macro language
5. plugins provide a way to add any functionality you like:
      examples include ReST viewers

[Edward K. Ream]

On Mon, May 28, 2012 at 2:51 AM, tfer <tfeth...@aol.com> wrote:
> Even rougher second draft:

Excellent. Now you are talking about why Leo isn't just another IDE
or just another outliner.

> Special headlines can be used to designated parts of Leo outlines that
> correspond to external text
> files.  Such headlines can have files generated from their subtrees by
> template(s) contained in body text. These templates determine how the file
> will be assembled from the descendent nodes.  Alternatively, other forms of
> these headlines can read in entire files and dissect them into outlines.
>
> One of the big ideas of Leo is that the body text in nodes is data, an
> analogy can be made to the cells in spreadsheets, here the data is not in a
> grid, but held in graphs, each node having a parent, possible siblings, and
> descendents. Leo has a dead simple DOM held in the python data structures
> that is easily interacted with via python.  All sorts of transforms,
> summarizing, and synthesizing are doable via python.

DOM's aren't held in data structures, they are the means of accessing
the data structures. So I'd say:

Leo scripts use a dead simple DOM (Document Object Model) to access
all the data in Leo outlines. Examples: p is the presently selected
outline node, p.b and p.h are the node's body text and headline and
p.v is the underlying data object for the node.

> More than just text can be held in a node, Leo has a way to add whatever you
> like via, what are called, "unknown attributes", or uA's.  These are unknown
> in the sense that Leo is set up to deal with text, but through through
> detectors  uA's are found, made to persist, and, via custom or plug-in
> coding dealt with.

It's ok to call them user attributes. I'd rewrite the last paragraph
something like this:

You can add addition *user data* (uA's for short) to any node. uA's
can be additional text, including references to external resources, or
even binary data. Once associated with a node, Leo will save the uA
to the .leo file, and restore the uA when you next load the file.
uA's persist arbitrary data for plugins or scripts. Leo scripts access
uA's with p.v.u.

Again, you are making excellent progress on the abstract. This is
important. I've learned from reading thousands of abstracts in
science journals that abstracts serve multiple functions:

1. They tell referees and eventual readers why the article is important.

2. They teach both referees and eventual readers something about the
overall field covered by the main article.

3. They summarize the article so that all readers will take away the
essential points without having to delve into the details in the main
article.

This your abstract now does.

Edward

[tfer]

Okay, this is what I've got currently.

Description:
Leo is a pure python, open source outliner, often used as an IDE. As a project manager, it handles all your files, no matter what language(s) you're using. Uniquely, it lets you to organize your projects below the file level, (elsewhere only doable informally with section comments). Using outlines supports thinking & organizing, allowing big/little picture focus shifts. Its great for code study.

Abstract:
What are the special, often unique facilities that Leo brings its users, and what advantages do they give? 
*External files and outline subtrees can be put into correspondence.
*It helps to keep code blocks small.
*Reorganizing is easy.
*Design and coding shifts are easy.
*Hard to code tasks can be further decomposed.
*Outline structure works as commenting.
*Custom, task oriented, side-views.
*Outline nodes are data.
*Custom, in outline, python macros.
*Extendable beyond just text.

Additional notes:
What are the special, often unique facilities that Leo brings its users, and what advantages do they give? 

External files and outline subtrees can be put into correspondence.  --  Special headlines can be used to designate parts of Leo outlines that correspond to external text files.  Such headlines can have files generated from their subtrees by template(s) contained in body text. These templates determine how the file will be assembled from the descendent nodes.  Alternatively, other forms of these headlines can read in entire files and dissect them into outlines.

It helps to keep code blocks small.  --  You are not faced with a vast empty plain of the file that is going to hold all your code, just a small area of body text that usually only has a half page of code.

Reorganizing is easy.  --  As your understanding grows, where you put things based on what type of task the code blocks are doing changes.  Instead of cutting and pasting, changing section comments to reorganize, - just add/rewrite headlines and move the headlines around in the outline pane.  The code blocks in the bodies follow right along.

Design and coding shifts are easy.  --  You are constantly shifting from "I'll need to do these tasks..." to actually write the code for one of those tasks.  Use Leo to capture both.  Tasks can quickly be given their own headline so they are not forgotten while you get involved coding up one of those tasks.

Hard to code tasks can be further decomposed.  --  When coding something difficult, perhaps at the edge of our understanding, you have the option of breaking it into sub-tasks, giving them headlines, and coding up the pieces in their body text.

Outline structure works as commenting.  --  Commenting, never popular to do, often out of sync with the code, is often replaced with "The code is the comment" maxim.  Here, the outline itself often shows what is being attempted, and helps you understand those 300 thousand lines of legacy code you've got to get a handle on.

Custom, task oriented, side-views.  --  Say you've got some debugging to do, or new functionality to add.  Only certain parts of the code are going to be relevant.  In a regular code editor, you're left jumping all around your file(s) making changes, hoping you haven't missed things or added side effects.  Leo lets you clone a portal to any node, and put that into a separate outline view that you can organize as you want to accomplish your task.  Any changes you make in these nodes, (or the sub-nodes they brought with them), are made everywhere those nodes appear in you outline, as they are in fact the same nodes.

Outline nodes are data.  --  One of the big ideas of Leo is that the body text in nodes are data.  An analogy can be made to the cells in spreadsheets, here the data is not in a grid, but held in graphs, each node having a parent, possible siblings, and descendents. Leo scripts use a dead simple DOM (Document Object Model) to access all the data in Leo outlines.  Examples: p is the presently selected outline node, p.b and p.h are the node's body text and headline and p.v is the underlying data object for the node.  Using this, all sorts of transforming, summarizing, and synthesizing scripts can be written in python.

Custom, in outline, python macros.  --  "@button macroName" in a headline, provides a click-able button that runs the python script placed in the node's body text.  This takes you far beyond any macro language when combined with "Outline nodes are data" idea above.

Extendable beyond just text.  --  You can add additional *user data* (uA's for short) to any node.  uA's can be additional text, including references to external resources, or even binary data.  Once associated with a node, Leo will save the uA to the .leo file, and restore the uA when you next load the file.  uA's persist arbitrary data for plugins or scripts. Leo scripts access uA's with p.v.u.

===================================================================================

I'm debating whether to put the "additional notes" section into the abstract.  The application states that the abstract will become public if the talk is accepted, so it will probably appear on the website which might help people decide to attend the talk.  Then again it might just be too much info and glaze some eyes over, plus, that would be too wordy for the printed program.

Perhaps I'll just add a short sentence to expand each point.

Tom

[tfer]

Trying out my own suggestion, I've changed the abstract to:

What are the special, often unique facilities that Leo brings its users, and what advantages do they give? 

*External files and outline subtrees can be put into correspondence.  --  Creating, sourcing, or both.
*It helps to keep code blocks small. -- Think note cards rather than reams of paper.
*Reorganizing is easy.  --  Just drag around headlines in the outline pane!
*Design and coding shifts are easy.  --  Capture design in headlines, fill in whenever.
*Hard to code tasks can be further decomposed. --  Name sub-tasks, fill in, shift focus by expanding/collapsing outline parts.
*Outline structure works as commenting.  --  Just the structure can convey intent.
*Custom, task oriented side-views.  --  More ways to see things, (portal guns for everyone!).
*Outline nodes are data.  --  Metaprogramming built in.
*Custom, in outline, python macros.  Instant buttons!
*Extendable beyond just text.  --  Add pictures, icons, widgets, urls, data records...

[Matt Wilkie]

I find the extended version more informative (and very good too!),
though it is a bit long to be considered an abstract; it's certainly
an overview. It might be the format. I find my eyes just drifting
over over the bullets without really reading or absorbing their
content. That could be equally due to my familiarity with the subject
too though.

Either way, I've been using Leo for a couple of years, though I still
consider myself a neophyte, and I found myself going "ahh, so that's
it" a few times while reading it. So, well done. :)

-matt

[Edward K. Ream]

On Wed, May 30, 2012 at 1:29 PM, Matt Wilkie <map...@gmail.com> wrote:

> I find the extended version more informative (and very good too!),

I agree completely. It's a superb summary.

Edward

[Edward K. Ream]

On Wed, May 30, 2012 at 12:35 PM, tfer <tfeth...@aol.com> wrote:
> Okay, this is what I've got currently.
>
> Description:

Excellent.

> Abstract:

Again, excellent. It would be good to have this summary seen as
widely as possible. You might ask the referees/organizers about its
length, but I would lobby hard for the full monty. It's hard to
convey what's unique with just short phrases.

However it turns out, your description should be placed prominently on
Leo's web site. Many thanks for your superb efforts. Nobody knows
better than I how difficult it is to describe Leo.

Edward