Re: Turning to documentation

[Edward K. Ream]

On Sun, Apr 2, 2017 at 8:23 PM, Joe Orr  wrote:

>
> Also, as part of Leo Viewer I made a couple of very simple intro tutorials
> here: https://github.com/kaleguy/leo-tutorials
>
> I'll probably add more or maybe I should be trying to use the existing
> ones. Any thoughts on that?
>

​As I implied in the other thread, these tutorials are ​are miles ahead of
anything I have ever done.

Anyway, to me the ultimate thing to add to Leo would be a screenshot
> capacity. Back in the day I wrote a program called Screenbook Maker but I
> abandoned it after VB6 code started to get hard to maintain. But I still
> need a tool to create screenshots tied with text and stored in some
> universal format like XML, JSON or YAML. Getting from there to a slick
> presentation is simple.
>

​That would be great.

I had forgotten about Terry's screen-capture commands. Enable the
screen_capture.py plugin to use them.  Much better than the plugins I wrote
;-)

Edward

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

['Terry Brown' via leo-editor]

On Sun, 2 Apr 2017 18:23:07 -0700 (PDT)
Joe Orr  wrote:

> Not sure I'm following this discussion completely, maybe I should
> post a new thread...
> 
> Anyway, I'm planning on adding presentations to Leo Viewer at some
> point using this: https://github.com/hakimel/reveal.js/

Reveal.js presentations in Leo are an interesting idea.  Reveal allows
you to write presentations in markdown, I've used Leo to edit these in
the past: http://tbnorth.github.io/git_for_r

[snip]

> Anyway, to me the ultimate thing to add to Leo would be a screenshot 
> capacity. Back in the day I wrote a program called Screenbook Maker

Screen shots of Leo, or something else?  Leo has

screen-capture-5sec and screen-capture-now commands that take
screenshots of Leo and save them
in /home//.leo/screen_captures/2017-04-02T20-33-04.png
Coincidentally a product of one of the previous Leo sprints I think.

Cheers -Terry

> but I abandoned it after VB6 code started to get hard to maintain.
> But I still need a tool to create screenshots tied with text and
> stored in some universal format like XML, JSON or YAML. Getting from
> there to a slick presentation is simple.
> 
> Joe
> 
> On Friday, February 10, 2017 at 10:58:34 AM UTC-5, Edward K. Ream
> wrote:
> >
> > On Fri, Feb 10, 2017 at 9:37 AM, lewis  > > wrote:
> >
> > Just thinking out aloud here as I read about your writing *before*
> > your 
> >> Aha. Is it possible to integrate the concept of chapters as you
> >> write your executable documents and are 'Composing script lists
> >> from a tree of nodes'?
> >>
> >
> > ​This is not likely to be useful in practice.  Outlines already can 
> > organize demo scripts. That's plenty good enough. Switching
> > chapters would just slow things down.
> >
> > Edward
> >
> 

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

[Joe Orr]

Not sure I'm following this discussion completely, maybe I should post a 
new thread...

Anyway, I'm planning on adding presentations to Leo Viewer at some point 
using this: https://github.com/hakimel/reveal.js/

Also, as part of Leo Viewer I made a couple of very simple intro tutorials 
here: https://github.com/kaleguy/leo-tutorials

I'll probably add more or maybe I should be trying to use the existing 
ones. Any thoughts on that? I made these because I need something super 
simple to fit into the Leo Viewer intro outline (see separate post).

Anyway, to me the ultimate thing to add to Leo would be a screenshot 
capacity. Back in the day I wrote a program called Screenbook Maker but I 
abandoned it after VB6 code started to get hard to maintain. But I still 
need a tool to create screenshots tied with text and stored in some 
universal format like XML, JSON or YAML. Getting from there to a slick 
presentation is simple.

Joe

On Friday, February 10, 2017 at 10:58:34 AM UTC-5, Edward K. Ream wrote:
>
> On Fri, Feb 10, 2017 at 9:37 AM, lewis  > wrote:
>
> Just thinking out aloud here as I read about your writing *before* your 
>> Aha. Is it possible to integrate the concept of chapters as you write your 
>> executable documents and are 'Composing script lists from a tree of nodes'?
>>
>
> ​This is not likely to be useful in practice.  Outlines already can 
> organize demo scripts. That's plenty good enough. Switching chapters would 
> just slow things down.
>
> Edward
>

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

[Offray Vladimir Luna Cárdenas]

And maybe from docs as mini programs to live docs as live mini-programs 
;-)... interesting times are coming from Leo and literate computing and 
maybe another important breakthrough in the 20+ Leo's history.


Cheers,

Offray


On 09/02/17 11:55, Edward K. Ream wrote:

​​
On Thu, Feb 9, 2017 at 8:55 AM, Edward K. Ream > wrote:


​> ​
The feeling is that good docs may be akin to small chunks of code
​.

I've spent the last hour or so working on my first "real" demo. As 
expected, this has suggested a few tweaks to the code, on master.


But a spectacular improvement, enabled by three lines of code, has 
arisen.  I'll explain it (brag about it) in another thread.


To return to the original intuition, thinking about docs as mini 
programs is getting more and more exciting. I'm pretty sure there is a 
breakthrough nearby...


Edward
--
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 post to this group, send email to leo-editor@googlegroups.com 
.

Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.


--
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

[Edward K. Ream]

On Friday, February 10, 2017 at 9:28:39 AM UTC-6, Edward K. Ream wrote:

I want to emphasize something.  Demo scripts can use *all *parts of Leo's 
> API to "run" Leo automatically. For example, this is one way to create a 
> new node:
>
> p = c.insertHeadline()
> p.h = 'a headline'
> p.b = 'some body text'
>

Recent revs make this work properly. See the change log 
.
 
There were some tricky issues with control and screen refresh.  The summary:

demo.start now takes an "auto_run=False" keyword arg. When True, demo.start 
runs each demo script one after the other. The demo.auto_run ivar is a copy 
of this arg. As shown in the example top-level script 
,
 
demo.teardown could insert inter-slide delays when self.auto_run is True.

Edward

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

[Edward K. Ream]

On Fri, Feb 10, 2017 at 9:37 AM, lewis  wrote:

Just thinking out aloud here as I read about your writing *before* your
> Aha. Is it possible to integrate the concept of chapters as you write your
> executable documents and are 'Composing script lists from a tree of nodes'?
>

​This is not likely to be useful in practice.  Outlines already can
organize demo scripts. That's plenty good enough. Switching chapters would
just slow things down.

Edward

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

[Edward K. Ream]

On Fri, Feb 10, 2017 at 9:28 AM, Edward K. Ream  wrote:

​> ​
Instant automation!  Do you see how cool this is?

​Although usually simple, ​the various setup/teardown methods help devs
maintain momentum and energy.
​ This is important, especially when confronting a long period of
experimentation.​


Edward

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

[Edward K. Ream]

​​
​​
On Fri, Feb 10, 2017 at 4:22 AM, Geoff Evans 
wrote:
​
​
​> ​
A good test is both
(a)  an illustration of something the program should do;
(b)  an ability to detect if the program isn't doing it.
In this light, tests appear as helpers toward understanding rather than
obstacles to be overcome.

​Interesting notion.​


​> ​
Why don't more people use Leo (or more of its capabilities)?
​...one part of the answer is that the documentation is hard to use.

Maybe, but there are more plausible reasons. First, millions of programmers
get their start on emacs.  Because their mates use emacs, they can easily
get their questions answered. They can literally look over the friend's
shoulder.

Second, emacs org-mode is good enough (for emacs users). It isn't Leo, but
for at least four years has had powerful scripting capabilities, which in
some ways are Leo's equal or better.

Third, because there are so many emacs and org-mode users, the resources
available to them are immense.  For example, this org-mode tutorial video
, and this longer one
. I haven't watched either
tutorial yet. I will as preparation for developing new Leo videos.

> [Docs should invite, guide, serve as a reference]

All reasonable goals. How do you propose to test them?

Edward

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

[lewis]

Just thinking out aloud here as I read about your writing *before* your 
Aha. Is it possible to integrate the concept of chapters as you write your 
executable documents and are 'Composing script lists from a tree of nodes'?
The idea appeals to me and it also possibly reveals how little I know about 
programming. But hey, of course that has nothing to do with aha moments and 
thinking out aloud.

Lewis

On Saturday, February 11, 2017 at 12:18:40 AM UTC+11, Edward K. Ream wrote:
>
> ​​
> On Thu, Feb 9, 2017 at 10:55 AM, Edward K. Ream  > wrote:
>
> ​> ​
> The feeling is that good docs may be akin to small chunks of code
> ​...​
>
> At some point in the last day or so, the phrase *executable docs* popped 
> into my head. Is that phrase itself a breakthrough?  I'm not sure. [No it's 
> not, but it's close].
>
> What *is* clear is that I've never before had so much energy writing 
> docs, or really, writing anything. Clearly, the "less said the better" 
> principle is a key ingredient. And so is intermixing words with example 
> code. It's kinda like using FAQ style for *everything*.
>
> Another thing that is clear to me now.  Composing script lists from a tree 
> of nodes, each node of which can contain multiple demo scripts, is a 
> *huge* breakthrough.  And it's one of the strengths of org-mode.
>
> Clearly, the phrase "executable documentation" perfectly describes the 
> script tree that drives a demonstration.  There is so much energy involved:
>
> 1. It's now dead easy to create and edit nodes.
> 2. Each node naturally describes one slide, or one thought.
> 3. Setup and teardown methods eliminate repetitious code from nodes.
> 4. Testing is instantaneous. Just run the demo.
>
> As I write this, I see that it might be useful to associate names with 
> slides.  That way, we could tell demo.start to start with the slide of a 
> given name.
>

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

[Edward K. Ream]

​​On Fri, Feb 10, 2017 at 7:18 AM, Edward K. Ream 
wrote:

​This post will be pre-writing for a new section in ​demo.md
.


​> ​
My task is now clear.  Create demos that* show Leo in action*!​

This really is a programming task. The example top-level script

in demo.md
 is
no toy.

The *setup *method defines the 'delta' ivar, incremented when changing font
magnification in Leo's body pane. The *teardown* method restores the
original font magnification. The Demo class catches all exceptions, so it
can call teardown in *all* cases.

The *setup_script* method calls demo.delete_widgets(), which frees
individual demo scripts from having to do so. See below for a practical use
for *teardown_script*.

I want to emphasize something.  Demo scripts can use *all *parts of Leo's
API to "run" Leo automatically. For example, this is one way to create a
new node:

p = c.insertHeadline()
p.h = 'a headline'
p.b = 'some body text'

This means that devs don't have to do *anything* "by hand" when creating a
demo.

*Demos are totally reproducible.*
One more cool thing. During development, it's fine to move from one slide
to the next using demo-next (bound to Ctrl-9 in the example top-level
node). Just before creating the video, we can define this *teardown_script*
method:

def teardown_script(self):
self.wait(self.inter_slide_wait)
self.next()

Instant automation!  Do you see how cool this is?

Edward

P. S. > ...it might be useful to associate names with slides.  That way, we
could tell demo.start to start with the slide of a given name.

A silly idea.  @ignore or @ignore-tree allow devs to skip already
"debugged" nodes.

EKR

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

[Geoff Evans]

This encouraging development prompts me to throw something into the mix 
that's been on my mind for a while.

1.  It starts with Edward's Stupendous Aha about tests from months ago, 
which goes roughly:
A good test is both
  (a)  an illustration of something the program should do;
  (b)  an ability to detect if the program isn't doing it.
In this light, tests appear as helpers toward understanding rather than 
obstacles to be overcome.

2.  Then there's a perennial question: Why don't more people use Leo (or 
more of its capabilities)?  In my mind (and there are those who agree with 
this), one part of the answer is that the documentation is hard to use.

3.  So:  ** What are the tests for documentation? **
Saying that documentation needs tests implies saying that it should *do* 
something, not just *contain* something.  I suggest that at the top level 
what it should do is:
  (a) Invite.  Persuade potential users that Leo offers something they 
want, that their current tools don't supply.  And that they can get at 
least a working version of what they want with a modest investment of 
effort.  Possible subjects for invitations: Leo as a whole; scripts; ILeo 
(how is it better than using %cpaste in a separate IPython window?); vi 
emulation.
  (b) Guide.  (aka Tutorial?)  Given someone who has decided to invest some 
effort, take her through the steps to reach some worthwhile goal.  Perhaps 
best implemented as a set of plateaus, each plateau having a set of 
signposts for choices of where to be guided next.
  (c) Be consulted.  Someone has started to use Leo regularly has a 
detailed question (How do I change the font size?  How do I make python 
indent using 3 spaces instead of 4?) and a generic question:  How do I 
navigate the documentation to answer the detailed question?  For the first 
of my examples, the best I can come up with is "Poke around in leoSettings 
for something that says 'font' and play with changing that in 
myLeoSettings"; for the second example, "I have no idea".

Of course, if I knew Leo better I could have said more sensible things 
here.  Chicken and egg.

Cheers,   geoff

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

[Edward K. Ream]

​​
On Thu, Feb 9, 2017 at 8:55 AM, Edward K. Ream  wrote:

​> ​
The feeling is that good docs may be akin to small chunks of code
​.

I've spent the last hour or so working on my first "real" demo. As
expected, this has suggested a few tweaks to the code, on master.

But a spectacular improvement, enabled by three lines of code, has arisen.
I'll explain it (brag about it) in another thread.

To return to the original intuition, thinking about docs as mini programs
is getting more and more exciting. I'm pretty sure there is a breakthrough
nearby...

Edward

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

[Edward K. Ream]

On Friday, February 3, 2017 at 6:35:48 AM UTC-6, Edward K. Ream wrote:

> There have been a number of excellent suggestions for Leo's documentation:
 
> Next: #356 Scripting documentation for new users of leoeditor. 

> Done: #388: wikiview.py plugin problem with new colorizing code 

> Done: #372: Support something like emacs electric url's 

> Deferred: #396: Show images in Leo's body pane 


I expect to spend *at least* a week revising tutorials and creating 
presentations with the new demo.py plugin. In fact, I don't want to set 
myself any deadline at all for 5.5b1, because...

While working on the demo docs 
, I 
am getting the vague stirrings that there is a breakthrough in 
communication lurking nearby. Part of it is the "less said the better" 
principle. But there is something else, too.

The feeling is that good docs may be akin to small chunks of code. 
Certainly, we want to intermix words and code. More importantly, the 
essence of Leo is a *process.*

This may be what newbies are *really *wanting when they say they want 
step-by-step *instructions*. In fact, they want to *see* Leo *in action*, 
in step-by-step increments.

For the first time, the demo.py plugin gives us all the chance to play with 
these notions. The fuzzy picture I have is of dozens, hundreds or even 
thousands of tiny *nuggets of experiece* to be imparted to newbies.  
Naturally, we want to get people going quickly, after only a few dozen :-) 
But getting there may require a many more. Deadlines are not my friend just 
now.

Edward

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Re: Turning to documentation

[Edward K. Ream]

On Friday, February 3, 2017 at 6:35:48 AM UTC-6, Edward K. Ream wrote:

> I have just added these items to the 5.5b1 list:

And another: #397: Emulate (and improve on) pyzo's "wizard" handling 


Edward

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

Turning to documentation

[Edward K. Ream]

There have been a number of excellent suggestions for Leo's documentation 
recent, especially #356 Scripting documentation for new users of leoeditor. 


To support tutorials, I have just added these items to the 5.5b1 list:

#388: wikiview.py plugin problem with new colorizing code 


#372: Support something like emacs electric url's 


And a new issue: #396: Show images in Leo's body pane 


It's embarrassing that Leo's body pane is so feeble.  This must be fixed 
for 5.5b1 so that we can present Leo in the best possible light.

Edward

-- 
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 post to this group, send email to leo-editor@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.