As the 'new' (since 2009) user John mentioned, I totally endorse what he
says about how friendly and helpful the Leo community is in dealing with
questions. But I'm also old enough to be fond of written documentation.
This note is one offering towards Edward's desire for outreach to more
users and how the documentation could serve that purpose. I am looking for
something that will persuade a non-user to try leo, and persuade a new user
that a small effort in learning a bit more often brings a big reward.
Years of editing and reviewing for international scientific journals, plus
decades of making my own mistakes, have taught me the value of just-in-time
delivery of ideas, and of writing to the interface not the implementation.
So before even the Tutorial (which is still basically about How rather
than What and Why) I envisage a section built around people's needs and
indicating how they would go about meeting them with Leo. Something like
(trying to use the format in Jacob Peck's scripting example):
-A Taste of Leo
Leo is a system that lets you enter information and keep track
of how it's organized. Leo's main window has two large parts
that contain your information: an outline pane toward the top
left and a body pane [I always toggle the split direction] on
the right. The body pane contains information related to the
highlighed headline in the outline pane; headline and body pane
together are referred to as a node.
-Staples
There are many ways to instruct Leo: commands, directives,
scripts, buttons, abbreviations .... This part gives
brief examples of the kind of thing each does.
-Command
Does something immediately.
You want to insert a new node into your outline:
Alt-X insert-node [Ctrl-I]
Typing 'Alt-X' put you in a minibuffer at the bottom of
the main window, where you type the rest of the
command. This is such a common command that there is a
keyboard shortcut for it. But there are scores of
commands, most of which have to be entered the Alt-X
way (tab completion can make it less onerous).
You want to seach for something in the outline:
Alt-X find [Ctrl-F]
is a flexible command that, for example, lets you
search only headlines, and offers search-and-replace.
-Directive
Doesn't do anything immediately, but sets up ground
rules that will be followed in that node and all
children until overridden.
You want syntax colouring appropriate the the language
you're programming in
@language python
turns it on.
You want to save a subtree in an external file where
another program can access it.
@file file.name
directs that the node and all children will be saved in
a separate file called file.name .
-Setting
Controls how a whole Leo session will look.
You always want your body pane to the right of the
outline pane, whereas by default Leo will put it below.
Edit the file myLeoSetttings.leo (which you access by
clicking the Settings tab near the top of the main
window -- or the Help tab in older Leo versions such
as the picture in the current Leo5.1 documentation) by
adding a line
@bool split_direction = vertical
Settings don't take efffect immediately, but only in
the next leo session you open. [Though when you're
experimenting to see how they work, you can put a
@settings tree in the outline you're working on,
add your lines there, and they take effect when you
save and reopen the file in the same Leo session.]
-Script
I can't give an example of something I want that a
script will do for me.
-Treats
This is the place to put some representative gems. I seem
to recall Edward suggesting this somewhere in the thread on
Leo's future, though I can't find it now. But they have to
be things that make a new user say: "I hadn't thought of
using Leo for that. Now that I think of it, I can see
wanting to. I'm confident now I can work out how for my
own needs."
But the first treat is obvious:
-Clone
You have a task that belongs in Project A, that you
need to work on next week. So you enter a node for
the task under <Project A>, type Ctrl-` , and you have
a copy of the node you can move to under <Do next week>
*and* when you modify your description in one place,
the same modifications happen in the other.
Okay, that's enough ignorant comment from me. People who really know Leo
can correct all the mistakes I've made and add more and better treats and
examples.
One other thought: there are places where the documentation has "Go here
for help" links. If they were to point to the leo-editor-users group,
rather than leo-editor, people might be less inhibited about using them.
It would feel less like interrupting the work of the developers.
geoff
On Sunday, August 30, 2015 at 5:53:24 PM UTC-2:30, john lunzer wrote:
>
> A new user recently said to me, "Leo is powerful and flexible -- and
> complex and bewildering". This is true. I believe it is always the goal of
> developers to make their software less complex and bewildering but keep in
> mind that Leo has been in development for over 20 years and has ~1.5
> million lines of code (IIRC). This puts it right up there with Vim and
> Emacs in terms of maturity. My own experience with Vim and Emacs have been
> quite similar to my experience with Leo. All three are powerful and
> flexible and complex and bewildering in their own right.
>
> I believe with tools of this weight and impact, there will always be an
> investment in learning them. They're all vast forests of features filled
> with hidden treasures and in the case of each of them he/she that invests
> in the tool will be rewarded for their effort. It is, however, the
> responsibility of the community (led by the developers) to help make that
> treasure hunt as enjoyable and adventurous as possible, as any good
> treasure hunt should be.
>
> And this is where Leo does not falter, in the helpfulness of its community
> (small though it may be). I will reiterate what Edward has said many times,
> do not struggle on your own if you are lost, confused, or bewildered.
> Please ask questions. If the documentation or examples do not meet your
> needs, please ask questions. In my own experience as a once new user (though
> there may be the occasional disagreement) you will not be chided,
> scorned, or belittled but will be met with more even more help than you
> originally asked for.
>
--
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 [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.
