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 <https://github.com/tbpassin/gf4-project/blob/devel/DEVELOPERS_READ_THIS.md> . 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.
