Thumb-nail Explanation Of Leo

[Thomas Passin]

Leo is notoriously to explain to people.  Most attempts start out something like "It's  a text editor, an IDE, oh, yes, a PIM, and so much more".  The listener is not very enlightened.

I've been bugged by this, so I have been working on refining the Leo's purpose and key concepts.  I'd like to share what I have so far, and hope that between us we can distill it even more clearly.

"Leo helps you create, edit, and understand the structure and contents of

collections of plain-text documents.

Plain-text documents can include text editor files, source code for program and documentation, and any other content that can be written as plain text, such as ReStructuredText, Markdown, .dot files that represent graph diagrams, to-do lists, and so on.

Structure includes both the arrangement of groups of related files, and structure that is important but rarely visualized in ordinary text files.

Leo's key concepts include a tree-like organization, nodes that contain the textual content, external files that can be contained as subtrees, and scripts that can add or change Leo's behaviors."

[Thomas Passin]

On Saturday, February 25, 2023 at 12:11:31 PM UTC-5 I wrote:

Leo is notoriously to explain to people.  Most attempts start out something like "It's  a text editor, an IDE, oh, yes, a PIM, and so much more".  The listener is not very enlightened.

That should have read  "Leo is notoriously hard to explain to people".

Sorry for the typo.

[Geoff Evans]

This reminds me of something I posted in 2012 (!)  It takes its starting point not from what Leo is, but from the sorts of things people might want to use and program a computer for in the first place which, for many of us, have very little to do with editing.  Here is is again:

--------------------------------

I should start by saying that I use Leo daily and wouldn't now consider
starting any project lasting more than a week without it. I'm immensely
grateful to Edward and the community of collaborators for creating and
polishing it. Two things prompt me nevertheless to write. First, I have
a strong feeling that there are ways I could be using it better, to make
my life even easier, if only I could manage to break into them; secondly,
Edward asks from time to time something like "Why isn't everybody using
Leo and what would it take to convert more people?" Maybe the following
will be a contribution.

When I started programming in Python a couple of years ago, and started
learning about object-oriented principles, one that struck me especially
was "Program to the interface, not the implementation." (It often takes
me a while to remember this when I'm working; but it always makes things
better when I do.) My "Aha" moment a couple of months ago came when I
realized that this wasn't true only of programming -- the same principle
applies to writing as well. Papers that jump right in to telling me what
the author did don't work nearly as well as those that start with the
reader and what s/he might care about and how the author proposes to
help with that.

[Isn't it interesting that the maxim I quoted above disobeys itself, because

it refers to the implementation in a computer program whereas the

real interface is the general act of communication and the primacy of the
receiver over the transmitter.]

So I envisage a tutorial starting as follows (sketch only):

Suppose you have a project that entails using some data, doing some
computations, and writing up the results. If you want to easily:

-- work on / store / contemplate the project as a unified whole
[Leo manages all relevant files in one outline]

-- see and work on one small part in its context
[Leo is an outliner]

-- copy thoughts, results from one context to another
[clones]

-- switch between interactive and batch processing
[iPython interface]

-- produce nice printed (literate?) documentation for those who don't
use Leo or don't do all their work glued to a computer screen
[rst3? noweb? Fweb? maybe little sample batch files with all the
required steps?]

-- ???
[scripting]
And here I'm stuck: Leo documentation assures me that scripting is an
amazingly powerful answer, but doesn't tell me what questions I might
like to ask, or what needs I might have, that it is an answer to. It
simply tells me what to do if I already know why I want to.

-- Here is where the community may want to contribute ways Leo has made
their working lives easier and more productive, by meeting existing needs
or wishes that had nothing intrinsically to do with Leo.

I envisage this as complementing the existing tutorial in leodocs. It
may provide an entrance that a different class of potential user would
find attractive. Or maybe I just need someone to gently point me to
where what I am suggesting already exists ;-)

Cheers, geoff evans

-------------------------------------------------------------------

Major offshoots in the last decade (e.g.ViewRendered) suggest further examples of "if you want to easily ..." that people who use and understand them could provide.

Confession:  Most of what I used to do with Leo I now do with Jupyter notebooks.  This is partly because my collaborators are more likely to know and use it,

but also possibly because the documentation tends to take it for granted that a feature is valuable so all that is necessary is to show me how (but not why)

to use it.

[Félix]

I also struggled a bit to write a concise and short explanation of what Leo is/does in the text introductions I wrote for LeoInteg and LeoJS... 

I enjoyed reading both of your posts! :)

If it can bring you some inspiration, the way I resume Leo as briefly as I can at the top of the readme for those projects is : 

Literate Programming with Directed Acyclic Graphs (dag)
Break your code down into sections structured as an outline, to derive or parse back your files
Leo is a fundamentally different way of using and organizing data, programs and scripts.

... and in the 'welcome screen' of LeoInteg I wrote: 

Use Leo, the Literate Editor with Outlines, to program with directed acyclic graphs, along with section-references, @others, and clones.

Félix

[Edward K. Ream]

On Saturday, February 25, 2023 at 2:57:25 PM UTC-6 Félix wrote:

I also struggled a bit to write a concise and short explanation of what Leo is/does in the text introductions I wrote for LeoInteg and LeoJS... 

...

the way I resume Leo as briefly as I can at the top of the readme for those projects is : 

Literate Programming with Directed Acyclic Graphs (dag)
Break your code down into sections structured as an outline, to derive or parse back your files
Leo is a fundamentally different way of using and organizing data, programs and scripts.

... and in the 'welcome screen' of LeoInteg I wrote: 

Use Leo, the Literate Editor with Outlines, to program with directed acyclic graphs, along with section-references, @others, and clones.

Thanks, Félix, for these descriptions. I don't usually refer to literate programming (LP) when talking about Leo because some people have had negative opinions about LP. Perhaps those opinions have changed.

Yes, there was lots to admire about LP ca. 1985. But imo Leo redefines LP:

- First, I dislike the narrative model of documentation. Imo, documentation is a reference, not a novel.

- Second, outline nodes provide space for as many comments, literate or not, as anyone could want.

- Third, outline structure plus clones is better than any index.

Also, Leo isn't an acronym, although sometimes I say it means Leonine editor with outlines :-)

Otoh, your description is accurate and concise. You may have a better sense of whether LP has become a bad word :-)

Edward

[Thomas Passin]

My last post was deleted for some reason.  

"Literate Programming with Directed Acyclic Graphs (dag)" - well, yes, but it's a very limited subset of what Leo can do.

"Use Leo, the Literate Editor with Outlines, to program with directed acyclic graphs, along with section-references, @others, and clones." - Well, yes, but a newcomer will not have any idea about what those terms mean or how they might be useful.

More and more I've been using Leo in different ways that are not programming-related at all.  I have a bookmark manager application - it's a set of scripts that runs in Leo - and I use that almost every day.  I have a zettel-kasten (we discussed that subject a year or two ago) and a related geneology app run by scripts that run in Leo, nothing to do with programming.  I sometimes write first drafts of documentation (not Leo documentation) in it before converting them to Libre Office .odt files.  I keep notes and time records for my small software consulting effort.  I wrote and maintain a Sphinx document that explains a software system of mine for other developers.  And so on.

I have come to realize that under it all, Leo helps us to create, modify, and otherwise work with the structure of documents that are base on plain text.  What's especially different about Leo is that it can help us surface structure that is otherwise hidden or implicit in a text file.  That's what we are doing when we break some text down into subtrees, when we use named sections and @others subtrees - we are imposing our ideas of a document's structure onto what would otherwise be a flat text file.  That's what we are doing when we create the source for a Sphinx document - we design the structure, make it manifest in the form of Leo subtrees, and write the content in Leo nodes located in those subtrees.  We are creating structured content with flat, plain-text files.

Literate Programming? Structured content.  Leo's source code?  Structured groups of plain-text yet structured files.  My bookmark manager? Structured collections of plain-text nodes, made useful by some Python programming.

Adding and maintaining structure and content - that's what Leo is all about.

[Steve Litt]

Thomas Passin said on Sat, 25 Feb 2023 09:11:31 -0800 (PST)

>Leo's key concepts include a tree-like organization, nodes that
>contain the textual content, external files that can be contained as
>subtrees, and scripts that can add or change Leo's behaviors."

I'd go the extra yard here and specifically say that, among other
things, Leo is a full featured outline processor. I know your preceding
paragraph implies this, but I'd spell it out for the 2% of the
population who actually outlines on a regular basis.

SteveT

Steve Litt
Autumn 2022 featured book: Thriving in Tough Times
http://www.troubleshooters.com/bookstore/thrive.htm

[Thomas Passin]

Thanks ... I'll see how to work that in.  It might fit in as one of the key concepts.

[Thomas Passin]

OK, how about this, adding in the outline idea -

"Leo helps you create, edit, and understand the structure and contents of collections of plain-text documents.

Plain-text documents can include text editor files, source code for program and documentation, and any other content that can be written as plain text, such as ReStructuredText, Markdown, .dot files that represent graph diagrams, to-do lists, and so on.

Structure includes both the arrangement of groups of related files, and structure that is important but rarely visualized in ordinary text files.  Structure is represented as an outline or tree, so Leo is also an effective outliner program.

Leo's key concepts include a tree-like (outline) organization, nodes that contain the textual content, external files that can be contained as subtrees, and scripts that can add or change Leo's behaviors.

Leo makes possible a divide-and-conquer strategy."

[Offray Vladimir Luna Cárdenas]

I think that your explanation is pretty complete.

For me, one of the most important aspects of Leo is that the structure of the plain-text documents is not only implicit, and in that sense "rarely visualized", as you put it, but also emergent and user provided. I was always able to take a plain text file and give it my structure, beyond the one implicit in the file via classes, scripts or methods.

I don't know how to convey this in your explanation, or if it wants to highlight this. For me, it was pretty important and one of the differentiated values of Leo, difficult to find elsewhere (maybe in OrgMode?)

HTH,

Offray

--
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 leo-editor+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/leo-editor/cb910058-21de-4399-aa2c-8cb91a3fdeecn%40googlegroups.com.

[Thomas Passin]

On Tuesday, February 28, 2023 at 12:03:04 PM UTC-5 off...@riseup.net wrote:

I think that your explanation is pretty complete.

For me, one of the most important aspects of Leo is that the structure of the plain-text documents is not only implicit, and in that sense "rarely visualized", as you put it, but also emergent and user provided. I was always able to take a plain text file and give it my structure, beyond the one implicit in the file via classes, scripts or methods.

I completely agree.  To my mind, this capability is one of Leo's strong points.  I've tried to incorporate your suggestion:

"Leo helps you create, edit, and understand the structure and contents of collections of plain-text documents.

Plain-text documents can include text editor files, source code for programs and documentation, and any other content that can be written as plain text, such as ReStructuredText, Markdown, .dot files that represent graph diagrams, to-do lists, and so on.

Structure includes both the arrangement of groups of related files, and structure that is important but rarely visualized in ordinary text files.  Structure is represented as an outline or tree, and Leo is an effective outliner program.

You can visualize structure in a text file by breaking it into sub-parts of your own choosing.  You can collect files and nodes into more than one grouping as you wish.

Leo's key concepts include a tree-like (outline) organization, nodes that contain the textual content, external files that can be contained as subtrees, and scripts that can add or change Leo's behaviors.

Leo makes possible a divide-and-conquer strategy."

I want to avoid making the statement too complicated and too hard to read, so I'm going to resist adding anything more unless it's really good.  I also don't want to include any specialized terms or concepts that many people won't be familiar with.  For that reason I haven't mentioned clones, though I'm sure that Edward would like it.  The purpose of clones is covered by "collect files and nodes into more than one grouping as you wish", and I do not think that the term itself would convey that notion to most non-Leonine readers.