New User's Guide To Leo

[Thomas Passin]

I've been thinking that there should be a book on Leo.  I don't think I've got another book left in me, but I'm not completely happy with the existing docs because I don't think they really match what a new user faces when trying to fire up Leo and use it the first few times.   (Also, I don't know that a publisher would be interested because the number of potential readers might seem too small).

So I am working on a guide for new users.  It's a Sphinx document, created, of course, in Leo.  It's at a very early stage so far, but I've put it up on my server so people can see it and make suggestions.

I've included the "elevator speech" for Leo that I posted in an earlier Groups thread.  One of the things that might be of the most interest at this point is the group of screenshots that I've labeled "Leo In Action".  They illustrate Leo being used for some of the kinds of tasks I've listed in an earlier section.

Please take a look and let me know what you think, bearing in mind that it's a very preliminary and incomplete draft.

New User's Guide To Leo

PS - If anyone else wants to try writing a Leo book, I'm a good technical and general editor.  I'd be glad to help out in that way.

PPS - Some of the screen shots are of a fresh install on a Linux virtual machine.  I'm running Windows 10, and I captured the Linux screen shots using a Windows screenshot utility, then converted them to png files with Windows Paint.  This was easier than trying to use a Linux screen capture utility in the VM, converting it into a png file, and then transferring it over to the Windows host.

[Edward K. Ream]

On Sun, May 7, 2023 at 11:56 PM Thomas Passin <tbp1...@gmail.com> wrote:

I've been thinking that there should be a book on Leo. 

+1

Please take a look and let me know what you think, bearing in mind that it's a very preliminary and incomplete draft.

New User's Guide To Leo

The first question most people would have would likely be: "Why should I care about yet another text editor?".

Edward

[Thomas Passin]

On Monday, May 8, 2023 at 7:29:01 AM UTC-4 Edward K. Ream wrote:

The first question most people would have would likely be: "Why should I care about yet another text editor?".

That's what I think too.  I've tried to address it by starting out with "what can you do with Leo"  And trying to make it more tangible with a number of screen shots ("Leo In Action").

[Edward K. Ream]

Imo, it should be one of the first sentences in the documentation.

I like what I see so far.

Edward

[Thomas Passin]

Keep checking back in with the link.  I'm making frequent changes for the time being.

[Edward K. Ream]

On Mon, May 8, 2023 at 5:02 PM Thomas Passin <tbp1...@gmail.com> wrote:

Keep checking back in with the link.  I'm making frequent changes for the time being.

Will do.

Edward

[Rob]

Looks good! May I also suggest to add LaTeX to the list of structured language support. There are more than a few of us LaTeX users on this group. I use Leo extensively as a LaTeX editor, especially finding the abbreviations a real time saver! My 2 cents.

Rob...

[Thomas Passin]

Thanks!  I have only used it for LaTex a few times and it didn't come to mind.  How do you create the actual document from the Leo outline?

[Rob]

I don't use Leo for that. I suppose I could, but I don't know how to create a suitable script. I'm on Windows, so I use Texnic Center to create the documents (PDFs). It's easy enough and allows for projects w/ multiple related documents. Perhaps I could write up my workflow at some point if anyone might find it useful.

Rob...

[Thomas Passin]

Texnic Center looks pretty good, at a quick glance.  Do you write an @clean TeX document in Leo, then process it into LaTex with Texnic Center?

[Rob]

I usually use @file w/ @language=tex for the xxx.tex files and Leo handles the comments appropriately. Works great!

I also have created several standard templates for typical document types w/ all the special preamble commands.

Rob...

[Thomas Passin]

Thanks... I'll add some material about LaTex.

[Offray Vladimir Luna Cárdenas]

Hi Thomas,

This looks pretty good! Thanks for the document and the effort behind.

The visual tour of what Leo is capable of is very compelling and a good showcase to new users about why to use Leo.

Keep the good work,

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/ddfc3aeb-f823-4134-8603-e3b95723900dn%40googlegroups.com.

[Thomas Passin]

Thanks!  Partly I'm motivated by the experience of opening a new program, seeing the window, and not being able to do a thing.  It's so frustrating!  I've had that happen a few times too many, and I wouldn't want new Leo users to go through it.  And partly because it's so hard to give non-Leoistas a feel for what they could do with Leo once they get into using it.

[Paul S. Wilson]

 All onboard.  Look forward to collaborate and learn

New Users' Guide to Leo

[Paul S. Wilson]

Two biggies after 20 years

Explain CLONING up front: not mind mapping or concept mapping, virtually unige

And for the love of whatever, make Windows / Mad installer

20-year blocker for magnitude adoption (10x 100x ?)

Paul

[Paul S. Wilson]

Sorry for tyoes

[Thomas Passin]

On Thursday, May 11, 2023 at 3:31:45 PM UTC-4 Paul wrote:

Explain CLONING up front: not mind mapping or concept mapping, virtually unige

Not as unique as you might think (e.g., TreeLine).  What's probably unique - or at least valuable - is how clones can be used with Leo.  This bit of the first section is about clones without using the term.  The term "clones" will not, I think, convey anything useful to new users -

"You can collect files and nodes into more than one grouping as you wish."

 

I do plan to add some material about clones, but I haven't worked out where or how yet. Clones do not have anything to do with what a new user faces after Leo has been opened.  That's what I'm most interested in for this Guide.

And for the love of whatever, make Windows / Mad installer

I'm not sure what you mean here.  Do you mean to package up Leo as an application so that even Python does not need to be installed separately?  There are a number of systems that are supposed to do that.  It might be worthwhile.  I don't know what you mean by "Mad". 

[Rob]

Echo what @Paul said about an installer. I believe the biggest obstacle to higher adoption of Leo isn't how to `use` Leo`, but how to install it. Every time I need to install on a new machine, I dread it! Consider Picard, a music tagging application. It is a Python program that contains all the dependencies needed to install and run (Python, Qt, etc.) I have managed to get Leo running on Windows (challenging, but doable) and a Mac. I hope I never have to install it on a Mac again as that was nearly impossible (at least for me). Perhaps @Paul meant Mac instead of Mad?

I have no idea how difficult it is to build a self-contained installer, but perhaps it might be worth the effort.

Rob...

[Thomas Passin]

I think it's not too hard on Windows, but that installer wouldn't work on a Mac.  Without actually having a Mac, I don't see how it would be possible. Linux is a whole other kettle of fish.  It's only on Linux that I've ever had any trouble.  On Windows, getting Leo going hasn't fought back for me.

[Thomas Passin]

I've extended the outline quite a bit.  Please take a look and let me know your reactions.  

New User's Guide To Leo

[Ludwig Schwardt]

Hi Rob,

I remember your struggles on the Mac. It inspired me to create the leo Homebrew formula back in the day. While I haven't used Leo since, I still hang out on the group. It's also interesting to see Leo pop up in VSCode, which I use daily.

I just received a shiny new MacBook Pro last week after 9 years on the previous one, so I might foolishly take up the challenge of producing an installer. It looks like PyInstaller works on Mac too. I'm also dusting off my Homebrew formulas and hope to clean up the leo one as well.

Last year I revived a colleague's 14-year-old Mac app, so I'm feeling limber :-)

Best regards,

Ludwig

[Rob]

Thanks, Ludwig for your work on the Homebrew project. I seem to remember I used HB to install Leo on my Mac. However, I have little to no recollection of the actual process. I suppose I could noodle it out again if I had to.

My MacBook Pro is going on 10+ years and it's fine for now. Not sure if I will ever spring for a newer one though. I'm getting pretty fed-up with Windows and haven't decided what's next when my current PC becomes a 'brick' in October, 2025 (can't update to Win11). Perhaps I'll make it a Linux box.

Rob...

[Ben Hancock]

Thomas writes:

I've been thinking that there should be a book on Leo.  I don't think I've got another book left in me, but I'm not completely happy with the existing docs because I don't think they really match what a new user faces when trying to fire up Leo and use it the first few times.  

I'm a new Leo user -- I've been programming in Python for 5+ years, but somehow only recently managed to discover it -- and think something like this would be very helpful. The tutorials, documentation, and Edward's YouTube videos are great. But what I think might be really useful are some step-by-step examples of common user stories.

For example:

* I'm a developer working on a small-ish Python project that I collaborate on with other people. How can I effectively use Leo to start editing my existing code base? How should I go about breaking up parts of the existing code into an outline (without actually breaking things)?

* I'm a technical writer working on a publication. How can I start writing my outline in Leo, and then save/export it to be shared with others in a plain text format (ReST, Markdown, etc.)?

* I manage a small website that's mostly just HTML and CSS. How can I use Leo's outlining framework to keep things more manageable and reduce duplication?

Those are just some ideas. And I apologize in advance if these things should be obvious to a newcomer. I've climbed a few text editor hills (vim, Emacs, acme, etc.) and I really like what I've seen of Leo, but I do find myself puzzling at what seem like basic questions.

Thanks all.

Ben

[Thomas Passin]

No apologies needed.  Leo is terrific, but it does have quite a learning curve.  In the end, I think many people end up with their own personalized workflows, most likely with some customized scripts to help.

I like your suggestions of user scenarios walkthroughs, and I think they don't really belong is the New User's Guide but in a collection of such walkthroughs.  In the draft outline of the Guide, I do have a subtree of "How Do I ..." topics, but they won't be to the depth you are talking about.  Also, probably no one person has the knowledge to handle all common scenarios.

If you have one or two of these kind of user scenarios of your own that you'd like suggestions for, try airing them here and maybe we can be of some help (and then the results can be collected into a scenario collection).  Leo is especially good for Sphinx documents written in ReST, BTW.  I can help with that one.  And for the code base scenario, Leo manages its own code base, which is in the LeoPyRef.leo outline (available from the File menu), and you can look at that to get ideas.  It's on GitHub, so it's clonable.  I myself have brought an existing Python project into Leo and put it on GitHub, so I can speak to that, if you are interested in  doing that.

[Rob]

Ben, I have used Leo successfully for many years in your examples 2 and 3. I'd be glad to write up typical workflows that I use if that would be useful, However, I agree w/ Thomas these probably aren't best suited for a new user guide.

Rob...

On Thursday, May 18, 2023 at 11:17:52 AM UTC-4 Ben Hancock wrote:

[Ben Hancock]

> On Thursday, May 18, 2023 at 11:17:52 AM UTC-4
> Ben Hancock wrote:
>

> > [...] what I think might be really useful are some step-by-step

> > examples of common user stories.
> >
> > For example:
> >
> > * I'm a developer working on a small-ish Python project that I
> > collaborate on with other people. How can I effectively use Leo to

> > start editing my existing code base? [...]

> >
> > * I'm a technical writer working on a publication. How can I start
> > writing my outline in Leo, and then save/export it to be shared
> > with others in a plain text format (ReST, Markdown, etc.)?
> >
> > * I manage a small website that's mostly just HTML and CSS. How can
> > I use Leo's outlining framework to keep things more manageable and
> > reduce duplication?
>

> On Thu, 18 May 2023 15:47:50 -0700 (PDT)
> Rob <lar...@gmail.com> wrote:
>
> Ben, I have used Leo successfully for many years in your examples 2
> and 3. I'd be glad to write up typical workflows that I use if that
> would be useful, However, I agree w/ Thomas these probably aren't best
> suited for a new user guide.

Hi Rob,

Thanks. I'd be grateful for your tips. It looks like I can probably get
a good start on point 2 (creating documents) with the "Creating
Documents from Outlines" tutorial[1], but if there are particular things
you've learned that would be helpful for a newbie, please share.

Learning more about how to use Leo to maintain a small website would be
great too. I currenly use a mix of HTML, Go templates, and pandoc for my
own site (I'm somehow never satisfied with static site generators out of
the box), but it seems like cloned nodes in Leo could go a long way to
making maintaining things like shared ``<head>`` sections easier, if I'm
understanding things right.

I appreciate that these might be too specific for a user guide, but I do
like Thomas' idea of compling tutorials like this (similar to the "worg"
tutorials for Emacs' org-mode[2]).

Cheers,
Ben

[1]: https://leo-editor.github.io/leo-editor/tutorial-rst3.html
[2]: https://orgmode.org/worg/org-tutorials/index.html

--
Ben Hancock

[Thomas Passin]

On Saturday, May 20, 2023 at 6:10:24 PM UTC-4 Ben Hancock wrote:

[snip]

Hi Rob,

Thanks. I'd be grateful for your tips. It looks like I can probably get
a good start on point 2 (creating documents) with the "Creating
Documents from Outlines" tutorial[1], but if there are particular things
you've learned that would be helpful for a newbie, please share.

I do have some good tips to pass on if you are using ReST and especially Sphinx, including one or two that are probably not quite obvious.  I think that using Leo with Sphinx to generate HTML documentation - once you learn certain key bits - is unbeatable for convenience.  For pdf, the output isn't as good.  That's mostly because the pdf generator doesn't produce the best quality output.  But I haven't tried generating pdf for several years and maybe things have improved.

 

Learning more about how to use Leo to maintain a small website would be
great too. I currenly use a mix of HTML, Go templates, and pandoc for my
own site (I'm somehow never satisfied with static site generators out of
the box), but it seems like cloned nodes in Leo could go a long way to
making maintaining things like shared ``<head>`` sections easier, if I'm
understanding things right.

Basically, if you can create some boilerplate that can be reused for many sites, then clones will probably be useful.  Bear in mind that clones should normally be within a particular outline;  clones between outlines can cause update problems.  Depending on the details of your workflow, it may be possible to write a Leo script to do all the steps, or some of them.  IOW, you could finalize the files, run the script, and have everything built.  Or, if you can write a batch file that can do all the steps, you could launch that file from within Leo.  And you can write and manage that batch file in Leo itself.

I believe that some people have worked out ways to use Jinja templates, but I'm not one of them.  If you can write Python scripts, you can get Leo itself to do a surprising number of things.

[Thomas Passin]

I've been plugging away New User's Guide.  I've also changed the name of the top-level file to index.html.  The rest of the URL remains the same:  New User's Guide.

[Thomas Passin]

On Thursday, May 18, 2023 at 11:17:52 AM UTC-4 Ben Hancock wrote:

Thomas writes:

I've been thinking that there should be a book on Leo.  I don't think I've got another book left in me, but I'm not completely happy with the existing docs because I don't think they really match what a new user faces when trying to fire up Leo and use it the first few times.  

I'm a new Leo user -- I've been programming in Python for 5+ years, but somehow only recently managed to discover it -- and think something like this would be very helpful. The tutorials, documentation, and Edward's YouTube videos are great. But what I think might be really useful are some step-by-step examples of common user stories.

For example:

* I'm a developer working on a small-ish Python project that I collaborate on with other people. How can I effectively use Leo to start editing my existing code base? How should I go about breaking up parts of the existing code into an outline (without actually breaking things)?

It's likely that your whole project can be contained by one Leo outline, or two if you want to separate out the documentation from the code. Basically, you would import all your project files into the Leo outline as "external" files (image files would be exceptions - there's not much point in keeping them in Leo since you won't be editing them with a text editor).  Then you would tune up and possibly re-organize the outline so that it makes the most sense to you.  After the outline has been saved, you would check to make sure that the project builds or runs right.   For many projects, the external files and the Leo outline(s) are put into GitHub or some other repository.

At this point, you can just edit the files within Leo, or you can continue to reorganize parts of it when that makes sense.  After that you can start thinking about creating scripts to automate actions that you used to kick off from the command line.

One consideration is whether your external files should be @file or @clean files.  @file files contain Leo "sentinels" that tell Leo how to recreate the outline structure of the file. @clean files do not contain any Leo markup.  It's easier for other (non-Leo) programmers to work with @clean files, but if they change the code structure too much, Leo may have trouble recreating the intended structure (it won't lose any code, though).  @file files can be annoying to other programmers because of Leo's embedded comments, but if they don't change or move the sentinels, everything will work fine.

I wrote a few paragraphs about this for my GF4 project: DEVELOPERS READ THIS.

For importing the files into an outline, the easiest way is to import them one-by-one using the File/Import Files/Import Any File menu item.  If there are too many files, this will get tedious (though it only needs to be done once), and you would probably do better using a recursive import script.  There is a model in LeoPyRef.leo - do a search for "recursive", find the example script, and then adjust it for your paths and files.  The imports will come in with absolute paths, and you should probably change them to relative paths - use the Find tab to do a search-and-replace on headlines only.

Some kinds of files you will probably want or need to keep as @clean files even if the bulk of your program files will be @file files.  These would be text files such as readme and markdown files, and possibly shell scripts (although these can be @file files too).

This sounds complicated, but it's not so bad in practice.  You only do it once and then as you get used to working within Leo you will start to wonder how you ever were able to manage the project any other way.