Re: New User's Guide To Leo

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

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/54d356d0-0a37-4e04-a385-9f9932480926n%40googlegroups.com.

Re: New User's Guide To Leo

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

On Saturday, May 20, 2023 at 7:37:29 PM UTC-4 Thomas Passin wrote:

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

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/cc23d419-c10b-4bc4-8f50-9e389a2dc264n%40googlegroups.com.