#@+leo-ver=5-thin
#@+node:ekr.20101028110015.8271: * @file slideshows.txt

#@@pagewidth 70
#@+all
#@+node:ekr.20101122071746.5046: ** How to create slideshows
To create a slideshow with sphinx:

cd leo\doc\html\slides\slideshow-name
make html

To generate screenshots from Wink & meld-slides & make-slide:

1. Plan slides carefully.  Insert @no-screenshot nodes for @slide
   nodes that will not have screenshots.

   Know the numbering of slides. I use the following kinds of comments
   to keep track of expected screenshots:

        .. no screenshot
        .. sc 5: description

2. Using the script in @slide nodes, take the screenshots in Wink.

   I use a **screenshots.bat** script that starts screenshots.leo with
   a standard size (900x700) window.

3. Create the screenshots using Wink's Export As Html command.
   The exact file names don't matter, but they should be .png files.

4. Create an @wink_path node in the @slideshow tree pointing
   to the screenshot folder.

5. Run the meld-slides command to create @url final output file nodes.

6. Double-click @url final output nodes to edit them in InkScape.

7. Run the make-slide command on the individual @slide nodes.
   The creates the @url built slide node and runs the actual make,
   which creates the _build directory in the slideshow directory.

8. The make-slide-show command is useful for quickly generating
   @url built slide nodes in batches.

9. Copy the *contents* of the *slideshow's* _build/html directory to
   the proper slideshow directory of the server. Do *not* just copy
   the entire _build directory to the server.
#@+node:ekr.20101025080245.5540: ** To do: slideshows
#@+node:ekr.20101115152915.4933: *3* Next
#@+node:ekr.20101113110328.4947: *4* Using @button nodes
#@+node:ekr.20101115152915.4934: *4* Using @url nodes
#@+node:ekr.20101121032151.5375: *3* Maybe
#@+node:ekr.20101113110328.4945: *4* Top 10 coolest features
#@+node:ekr.20101113110328.4946: *4* How to make slide shows
#@+node:ekr.20101014034526.5294: *4* IPython
- Execute IPython scripts from Leo.
- Execute Leo scripts from IPython.
#@+node:ekr.20101014034526.5295: *4* Vim & Emacs
#@+node:ekr.20101025080245.5529: *4* leoremote plugin
@nocolor-node

Ville's server code to interact with a running Leo
http://mail.google.com/mail/#inbox/12adebe2ffe80572

Reusing Emacs instances with gnuserv
http://www.debian-administration.org/articles/257

#@+node:ekr.20101025080245.5546: *4* @url Document Ville's server
http://mail.google.com/mail/#inbox/12adebe2ffe80572
#@+node:ekr.20101010141953.5028: *4* @slideshow Leo's NSIS Installer
#@+node:ekr.20101010141953.5029: *5* @title_pattern = Leo's NSIS Installer: Slide %(slide_number)s
#@+node:ekr.20101010141953.5030: *5* @slide 001
.. _`here`:     http://www.nullsoft.com/free/nsis/
.. _`Winamp`:   http://www.winamp.com/

Nullsoft, the makers of the `Winamp`_ MP3 software, have released a powerful free
installer called NSIS, available `here`_. This application allows you to make
installation packages for Windows applications.

You create NSIS packages by writing a NSIS script and then compiling it.
Depending on the application, NSIS can often be a better choice than more
expensive installation generators, since NSIS installations are easy to create,
are small and fast, and yet can be configured with many features.

#@+node:ekr.20101010141953.5031: *5* @slide 002
When you install Leo, you'll find that it comes with a script for generating an
installer for Leo. This script is called leo-<version>.nsi, and is distributed
in the Leo file leo/dist/leoDist.leo.

If you have NSIS installed, right-clicking on a .nsi file will give you the
option of compiling the script to create a package.

.. image:: slide-002.png

#@+node:ekr.20101010141953.5032: *6* @screenshot
#@+node:ekr.20101010141953.5033: *7* Take screenshot of the compile .nsi dialog in a Windows folder
#@+node:ekr.20101010141953.5034: *6* @pause
#@+node:ekr.20101010141953.5038: *6* @url screenshot
c:/leo.repo/trunk/leo/doc/html/slides/leos-nsis-installer/screenshot-002.png
#@+node:ekr.20101010141953.5039: *6* @url working file
c:/leo.repo/trunk/leo/doc/html/slides/leos-nsis-installer/screenshot-002.svg
#@+node:ekr.20101010141953.5040: *6* @url final output file
c:/leo.repo/trunk/leo/doc/html/slides/leos-nsis-installer/slide-002.png
#@+node:ekr.20101011071655.4918: *6* @url built slide
c:\leo.repo\trunk\leo\doc\html\slides\leos-nsis-installer\_build\html\slide-002.html
#@+node:ekr.20101011092154.4923: *5* @slide 003
Since the NSIS script for the Leo installation is included in the Leo
distribution in the nsis.leo file, it is easy to understand the how the script
works. This .nsi file creates an installer that packages all of the Leo program
files, and creates a desktop shortcut, a Program Menu item, and the file
association for .leo files.
#@+node:ekr.20101011092154.4924: *5* @slide 004
In this screenshot we're looking at the code that checks to see whether Python
has been installed.

Since Leo is a Python application, modifying this installation script to create
a script to build a Windows installer for your own Python application is
relatively simple. You would leave this section alone, and check other sections
for the program name "Leo", and change these to your program name.
#@+node:ekr.20101011092154.4925: *5* @slide 005
#@+node:ekr.20101011071655.4919: *4* @slideshow Whetting Your Appetite
@pagewidth 50
#@+node:ekr.20101013072903.5219: *5* @slide What you can do with Leo
This slideshow shows some of the things you can do
with Leo
#@+node:ekr.20101013072903.5220: *6* @no-screenshot
#@+node:ekr.20101013072903.5221: *5* @slide Leo's main window
Leo's main window consists of an **outline pane**
(1), a **body pane** (2) and a **log pane** (3).
All data in Leo resides in **nodes**. A node
consists of **headline text** and **body text**.
The outline pane shows headlines. The body pane
pane shows the body text of the presently selected
node. Messages from Leo appear in the log pane.

#@+node:ekr.20101011071655.4920: *5* @slide A Personal Information Manager
You can use Leo as a PIM.

As with other outliners, Leo outlines show 
#@+node:ekr.20101011103613.4930: *5* @slide A Better PIM
Leo is a better pim.
#@+node:ekr.20101011103613.4942: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\whetting-your-appetite\_build\html\slide-003.html
#@+node:ekr.20101012083118.5245: *5* @slide External Files
#@+node:ekr.20101011103613.4933: *5* @slide A Scripting Environment
The body text of any node can contain a Python script.

You execute the script with (Ctrl-B) Leo's execute-script command.
#@+node:ekr.20101011103613.4943: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\whetting-your-appetite\_build\html\slide-005.html
#@+node:ekr.20101011103613.4934: *5* @slide Better Scripting
All Leo scripts have access to three predefined constants: c, g and p.
#@+node:ekr.20101011103613.4944: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\whetting-your-appetite\_build\html\slide-006.html
#@+node:ekr.20101011103613.4938: *5* @slide Better Scripting, Part Deux
All Leo scripts have full access to the outline in which the scripts reside. The
following scripts, executed from Leo's body pane, will print the headlines of
all the nodes of the outline, properly indented::

    for p in c.all_positions():
        print '%s%s' % (' '*p.level(),p.h)
#@+node:ekr.20101011103613.4945: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\whetting-your-appetite\_build\html\slide-007.html
#@+node:ekr.20101011103613.4935: *5* @slide Outlines Create New Leo Commands
Discuss @button nodes
#@+node:ekr.20101011103613.4946: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\whetting-your-appetite\_build\html\slide-008.html
#@+node:ekr.20101011103613.4937: *5* @slide Outlines Create Restructured Text
Leo outlines make it easy to create Restructured Text (rST) documents.

Within @rst trees, nodes correspond to rST sections. Naturally, the outline
level of a node in the Leo outline determines the section's level in the
resulting document.
#@+node:ekr.20101011111455.4965: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\whetting-your-appetite\_build\html\slide-010.html
#@+node:ekr.20101007082321.4357: *4* @slideshow What is Leo
By Joe Orr.
#@+node:ekr.20101009171445.4637: *5* @title_pattern = What is Leo? Slide %(slide_number)s
#@+node:ekr.20101008061729.4372: *5* @slide 001
Leo is a unique, powerful computer program that you can use to **organize**,
**analyze** and **describe** text and text files. Leo is a free and open
software written by Edward K. Ream. For information about downloading Leo, see
the **installation** tutorial in this series. Leo runs on Windows, Mac, or
Linux.

Use Leo:

- To brainstorm a new project.
- As a Personal Information Manager.
- To add multiple outlines and commentary to any text file.
- To create and organize computer programs.
- To apply computer scripts to any kind of data.

Because Leo is unlike other tools you may have used, a series of examples may be
the best way to demonstrate what can be done with Leo.
#@+node:ekr.20101010121134.4703: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\what-is-leo\_build\html\slide-001.html
#@+node:ekr.20101008061729.4373: *5* @slide 002
From one perspective, Leo is an **outlining editor**. This is a screenshot of
Leo. The arrow shows the outline pane. (A later tutorial explains how to create
an outline like the one in the screenshot).

.. image:: slide-002.png

#@+node:ekr.20101008061729.4384: *6* @screenshot
#@+node:ekr.20101008061729.4385: *7* To Do List
#@+node:ekr.20101008061729.4386: *8* Urgent
#@+node:ekr.20101008061729.4387: *8* Important
#@+node:ekr.20101008061729.4388: *8* Soon
#@+node:ekr.20101008061729.4389: *8* Whenever
#@+node:ekr.20101008061729.4390: *7* Diary
#@+node:ekr.20101008061729.4391: *8* 2009
#@+node:ekr.20101008061729.4392: *9* Jan 1
#@+node:ekr.20101008061729.4393: *8* 2010
#@+node:ekr.20101008061729.4396: *6* @select To Do List
#@+node:ekr.20101010121134.4704: *6* @edit
#@+node:ekr.20101010121134.4716: *6* @url screenshot
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-002.png
#@+node:ekr.20101010121134.4717: *6* @url working file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-002.svg
#@+node:ekr.20101010121134.4718: *6* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/slide-002.png
#@+node:ekr.20101010121134.4719: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\what-is-leo\_build\html\slide-002.html
#@+node:ekr.20101008061729.4398: *5* @slide 003
Clicking on the open triangle will open the indicated node.

.. image:: slide-003.png

#@+node:ekr.20101009115705.4583: *6* @screenshot
#@+node:ekr.20101009115705.4584: *7* To Do List
My to-do list.
#@+node:ekr.20101009115705.4585: *8* Urgent
#@+node:ekr.20101009115705.4586: *8* Important
#@+node:ekr.20101009115705.4587: *8* Soon
#@+node:ekr.20101009115705.4588: *8* Whenever
#@+node:ekr.20101009115705.4589: *7* Diary
#@+node:ekr.20101009115705.4590: *8* 2009
#@+node:ekr.20101009115705.4591: *9* Jan 1
#@+node:ekr.20101009115705.4592: *8* 2010
#@+node:ekr.20101008061729.4420: *6* @select 2009
#@+node:ekr.20101010121134.4731: *6* @url screenshot
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-003.png
#@+node:ekr.20101010121134.4732: *6* @url working file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-003.svg
#@+node:ekr.20101010121134.4746: *6* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/slide-003.png
#@+node:ekr.20101010121134.4747: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\what-is-leo\_build\html\slide-003.html
#@+node:ekr.20101008061729.4522: *5* @slide 004
Here the node has been opened. Clicking on the box again will close the node.

.. image:: slide-004.png

#@+node:ekr.20101009124842.4595: *6* @screenshot
#@+node:ekr.20101009124842.4596: *7* To Do List
@nocolor-node

My to-do list.
#@+node:ekr.20101009124842.4597: *8* Urgent
#@+node:ekr.20101009124842.4598: *8* Important
#@+node:ekr.20101009124842.4599: *8* Soon
#@+node:ekr.20101009124842.4600: *8* Whenever
#@+node:ekr.20101009124842.4601: *7* Diary
@nocolor-node

#@+node:ekr.20101009124842.4602: *8* 2009
#@+node:ekr.20101009124842.4603: *9* Aug
#@+node:ekr.20101009211009.4624: *9* Jul
#@+node:ekr.20101009211009.4623: *9* Jun
#@+node:ekr.20101009211009.4625: *9* May
#@+node:ekr.20101009211009.4626: *9* Apr
#@+node:ekr.20101009211009.4627: *9* Mar
#@+node:ekr.20101009211009.4628: *9* Feb
#@+node:ekr.20101009211009.4629: *9* Jan
#@+node:ekr.20101009124842.4604: *8* 2010
#@+node:ekr.20101009124842.4606: *6* @select 2009
#@+node:ekr.20101009124842.4607: *6* @edit
#@+node:ekr.20101010121134.4766: *6* @url screenshot
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-004.png
#@+node:ekr.20101010121134.4767: *6* @url working file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-004.svg
#@+node:ekr.20101010121134.4768: *6* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/slide-004.png
#@+node:ekr.20101010121134.4769: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\what-is-leo\_build\html\slide-004.html
#@+node:ekr.20101008061729.4518: *5* @slide 005
Here the indicated node has been closed.

.. image:: slide-005.png

#@+node:ekr.20101009212539.4682: *6* @screenshot
#@+node:ekr.20101009212539.4683: *7* To Do List
My to-do list.
#@+node:ekr.20101009212539.4684: *8* Urgent
#@+node:ekr.20101009212539.4685: *8* Important
#@+node:ekr.20101009212539.4686: *8* Soon
#@+node:ekr.20101009212539.4687: *8* Whenever
#@+node:ekr.20101009212539.4688: *7* Diary
#@+node:ekr.20101009212539.4689: *8* 2009
#@+node:ekr.20101009212539.4690: *9* Aug
#@+node:ekr.20101009212539.4691: *9* Jul
#@+node:ekr.20101009212539.4692: *9* Jun
#@+node:ekr.20101009212539.4693: *9* May
#@+node:ekr.20101009212539.4694: *9* Apr
#@+node:ekr.20101009212539.4695: *9* Mar
#@+node:ekr.20101009212539.4696: *9* Feb
#@+node:ekr.20101009212539.4697: *9* Jan
#@+node:ekr.20101009212539.4698: *8* 2010
#@+node:ekr.20101009212539.4746: *6* @select 2009
#@+node:ekr.20101009212539.4699: *6* @edit
#@+node:ekr.20101009213545.4670: *6* @url screenshot
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-005.png
#@+node:ekr.20101009213545.4671: *6* @url working file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-005.svg
#@+node:ekr.20101009213545.4672: *6* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/slide-005.png
#@+node:ekr.20101010121134.4814: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\what-is-leo\_build\html\slide-005.html
#@+node:ekr.20101008061729.4521: *5* @slide 006
Clicking on a node headline (1) will show the text for that node in the body
pane (2) below. The body pane is a text editor--you can enter, delete or change
text here by typing it in.

.. image:: slide-006.png

#@+node:ekr.20101009213545.4692: *6* @screenshot
#@+node:ekr.20101009213545.4693: *7* To Do List
@nocolor

My to-do list.
#@+node:ekr.20101009213545.4694: *8* Urgent
1. Make Leo tutorials.  The world is waiting.

2. Pay phone bill or the world will never know.
#@+node:ekr.20101009213545.4695: *8* Important
#@+node:ekr.20101009213545.4696: *8* Soon
#@+node:ekr.20101009213545.4697: *8* Whenever
#@+node:ekr.20101009213545.4698: *7* Diary
@nocolor
#@+node:ekr.20101009213545.4699: *8* 2009
#@+node:ekr.20101009213545.4700: *9* Aug
#@+node:ekr.20101009213545.4701: *9* Jul
#@+node:ekr.20101009213545.4702: *9* Jun
#@+node:ekr.20101009213545.4703: *9* May
#@+node:ekr.20101009213545.4704: *9* Apr
#@+node:ekr.20101009213545.4705: *9* Mar
#@+node:ekr.20101009213545.4706: *9* Feb
#@+node:ekr.20101009213545.4707: *9* Jan
#@+node:ekr.20101009213545.4708: *8* 2010
#@+node:ekr.20101009213545.4709: *6* @edit
#@+node:ekr.20101009213545.4710: *6* @select Urgent
#@+node:ekr.20101010121134.4810: *6* @url screenshot
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-006.png
#@+node:ekr.20101010121134.4811: *6* @url working file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-006.svg
#@+node:ekr.20101010121134.4812: *6* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/slide-006.png
#@+node:ekr.20101010121134.4813: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\what-is-leo\_build\html\slide-006.html
#@+node:ekr.20101008061729.4523: *5* @slide 007
You can save the outline in a .leo file.  Click File:Save (or Ctrl-S).

.. image:: slide-007.png

#@+node:ekr.20101010121134.4832: *6* @screenshot
#@+node:ekr.20101010121134.4833: *7* To Do List
@nocolor

My to-do list.
#@+node:ekr.20101010121134.4834: *8* Urgent
1. Make Leo tutorials.  The world is waiting.

2. Pay phone bill or the world will never know.
#@+node:ekr.20101010121134.4835: *8* Important
#@+node:ekr.20101010121134.4836: *8* Soon
#@+node:ekr.20101010121134.4837: *8* Whenever
#@+node:ekr.20101010121134.4838: *7* Diary
@nocolor
#@+node:ekr.20101010121134.4839: *8* 2009
#@+node:ekr.20101010121134.4840: *9* Aug
#@+node:ekr.20101010121134.4841: *9* Jul
#@+node:ekr.20101010121134.4842: *9* Jun
#@+node:ekr.20101010121134.4843: *9* May
#@+node:ekr.20101010121134.4844: *9* Apr
#@+node:ekr.20101010121134.4845: *9* Mar
#@+node:ekr.20101010121134.4846: *9* Feb
#@+node:ekr.20101010121134.4847: *9* Jan
#@+node:ekr.20101010121134.4848: *8* 2010
#@+node:ekr.20101010141334.4791: *6* @select Urgent
#@+node:ekr.20101010121134.4849: *6* @pause
#@+node:ekr.20101010121134.4868: *6* @url screenshot
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-007.png
#@+node:ekr.20101010121134.4869: *6* @url working file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-007.svg
#@+node:ekr.20101010140842.4755: *6* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/slide-007.png
#@+node:ekr.20101010140842.4756: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\what-is-leo\_build\html\slide-007.html
#@+node:ekr.20101008061729.4524: *5* @slide 008
Here we will save our outline in a file named "pim.leo"

.. image:: slide-008.png

#@+node:ekr.20101010141334.4772: *6* @screenshot
#@+node:ekr.20101010141334.4773: *7* To Do List
@nocolor

My to-do list.
#@+node:ekr.20101010141334.4774: *8* Urgent
1. Make Leo tutorials.  The world is waiting.

2. Pay phone bill or the world will never know.
#@+node:ekr.20101010141334.4775: *8* Important
#@+node:ekr.20101010141334.4776: *8* Soon
#@+node:ekr.20101010141334.4777: *8* Whenever
#@+node:ekr.20101010141334.4778: *7* Diary
@nocolor
#@+node:ekr.20101010141334.4779: *8* 2009
#@+node:ekr.20101010141334.4780: *9* Aug
#@+node:ekr.20101010141334.4781: *9* Jul
#@+node:ekr.20101010141334.4782: *9* Jun
#@+node:ekr.20101010141334.4783: *9* May
#@+node:ekr.20101010141334.4784: *9* Apr
#@+node:ekr.20101010141334.4785: *9* Mar
#@+node:ekr.20101010141334.4786: *9* Feb
#@+node:ekr.20101010141334.4787: *9* Jan
#@+node:ekr.20101010141334.4788: *8* 2010
#@+node:ekr.20101010141334.4793: *6* @select Urgent
#@+node:ekr.20101010141334.4789: *6* @pause
#@+node:ekr.20101010141953.4835: *6* @url screenshot
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-008.png
#@+node:ekr.20101010141953.4836: *6* @url working file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-008.svg
#@+node:ekr.20101010141953.4837: *6* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/slide-008.png
#@+node:ekr.20101010141953.4838: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\what-is-leo\_build\html\slide-008.html
#@+node:ekr.20101008061729.4525: *5* @slide 009
The file is now saved, and the file appears in the title bar.

.. image:: slide-009.png

#@+node:ekr.20101010141953.4856: *6* @screenshot
#@+node:ekr.20101010141953.4857: *7* To Do List
@nocolor

My to-do list.
#@+node:ekr.20101010141953.4858: *8* Urgent
1. Make Leo tutorials.  The world is waiting.

2. Pay phone bill or the world will never know.
#@+node:ekr.20101010141953.4859: *8* Important
#@+node:ekr.20101010141953.4860: *8* Soon
#@+node:ekr.20101010141953.4861: *8* Whenever
#@+node:ekr.20101010141953.4862: *7* Diary
@nocolor
#@+node:ekr.20101010141953.4863: *8* 2009
#@+node:ekr.20101010141953.4864: *9* Aug
#@+node:ekr.20101010141953.4865: *9* Jul
#@+node:ekr.20101010141953.4866: *9* Jun
#@+node:ekr.20101010141953.4867: *9* May
#@+node:ekr.20101010141953.4868: *9* Apr
#@+node:ekr.20101010141953.4869: *9* Mar
#@+node:ekr.20101010141953.4870: *9* Feb
#@+node:ekr.20101010141953.4871: *9* Jan
#@+node:ekr.20101010141953.4872: *8* 2010
#@+node:ekr.20101010141953.4873: *6* @select Urgent
#@+node:ekr.20101010141953.4896: *6* @pause
#@+node:ekr.20101010141953.4897: *6* @edit
#@+node:ekr.20101010141953.4916: *6* @url screenshot
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-009.png
#@+node:ekr.20101010141953.4917: *6* @url working file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-009.svg
#@+node:ekr.20101010141953.4918: *6* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/slide-009.png
#@+node:ekr.20101010141953.4919: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\what-is-leo\_build\html\slide-009.html
#@+node:ekr.20101008061729.4526: *5* @slide 010
You've just seen an introduction to Leo as an outlining editor. You can use Leo
to make an outline, with optional text for each outline element. You can save
the outline to a file. Outlines are explained more in a later tutorial in this
series.

  *The outlining capability of Leo goes far beyond what has just been demonstrated,
  including multipath outlines, and multiple outlines in one file.*

What we've shown so far is no different from other outlining editors. What makes
Leo unique is the addition of a new feature. **Using simple directives, you can
instruct Leo to extract text from any number of nodes, in any order, and write
the text to a new file**. We call files created or managed from within a Leo
outline **external file**. You can also embed outline information in the
external file, giving Leo the ability to read the text pieces back into the Leo
outline, even if they have been changed.

In effect, Leo is a **meta-text** editor. It gives you the ability to create a
structural document for a non structured document, or a document that is
structured in some other way.

What does this mean in practice? Some examples should help clarify things...
#@+node:ekr.20101010141953.4922: *6* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\what-is-leo\_build\html\slide-010.html
#@+node:ekr.20101008061729.4527: *5* @slide 011
Here is the "pim.leo" file again. We have:

1. Selected the "Diary" node.
2. Typed Ctrl-H to start editing the headline.
   (You can also edit headlines with the Edit:Edit Headline...:Edit Headline command.

.. image:: slide-011.png

#@+node:ekr.20101010141953.4940: *6* @screenshot
#@+node:ekr.20101010141953.4941: *7* To Do List
@nocolor

My to-do list.
#@+node:ekr.20101010141953.4942: *8* Urgent
1. Make Leo tutorials.  The world is waiting.

2. Pay phone bill or the world will never know.
#@+node:ekr.20101010141953.4943: *8* Important
#@+node:ekr.20101010141953.4944: *8* Soon
#@+node:ekr.20101010141953.4945: *8* Whenever
#@+node:ekr.20101010141953.4946: *7* Diary
@nocolor

This is my diary.
#@+node:ekr.20101010141953.4947: *8* 2009
#@+node:ekr.20101010141953.4948: *9* Aug
#@+node:ekr.20101010141953.4949: *9* Jul
#@+node:ekr.20101010141953.4950: *9* Jun
#@+node:ekr.20101010141953.4951: *9* May
#@+node:ekr.20101010141953.4952: *9* Apr
#@+node:ekr.20101010141953.4953: *9* Mar
#@+node:ekr.20101010141953.4954: *9* Feb
#@+node:ekr.20101010141953.4955: *9* Jan
#@+node:ekr.20101010141953.4956: *8* 2010
#@+node:ekr.20101010141953.4958: *6* @pause
#@+node:ekr.20101010141953.4957: *6* @select Diary
#@+node:ekr.20101010141953.5023: *6* @url screenshot
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-011.png
#@+node:ekr.20101010141953.5024: *6* @url working file
c:/leo.repo/leo-editor/leo/doc/html/slides/what-is-leo/screenshot-011.svg
#@+node:ekr.20101008061729.4528: *5* @slide 012
#@+node:ekr.20101008061729.4529: *5* @slide 013
#@+node:ekr.20101008061729.4530: *5* @slide 014
#@+node:ekr.20101008061729.4531: *5* @slide 015
#@+node:ekr.20101008061729.4532: *5* @slide 016
#@+node:ekr.20101008061729.4533: *5* @slide 017
#@+node:ekr.20101008061729.4534: *5* @slide 018
#@+node:ekr.20101008061729.4535: *5* @slide 019
#@+node:ekr.20101008061729.4536: *5* @slide 020
#@+node:ekr.20101008061729.4537: *5* @slide 021
#@+node:ekr.20101008061729.4539: *5* @slide 022
#@+node:ekr.20101008061729.4540: *5* @slide 023
#@+node:ekr.20100821182153.4345: ** @slideshow Installation
#@+node:ekr.20101014034526.5299: *3* @slide Overview
.. _`Download Python`: http://www.python.org/download/
.. _`packaged version`: https://sourceforge.net/projects/leo/files/Leo/
.. _`Leo's download page`: https://sourceforge.net/projects/leo/files/Leo/
.. _`next slide`: slide-002.html

**Installing on Windows: using Leo's single-click installer** 

1. Install Python: `Download Python`_, save to your desktop, then
   double-click on the saved file.

   Python is software for creating and running computer programs.
   Leo requires Python 2.6 or later, or Python 3.0 or later.

2. Install Qt. Get the binary package of PyQt from: 
   http://www.riverbankcomputing.co.uk/software/pyqt/download

   The version of PyQt that you download must match the version of your Python.

3. Download the latest Leo installer from `Leo's download page`_.
   It will be called something like LeoSetup-<version>.exe

4. Run the installer.

**Installing Leo from Linux packages**

Linux users are best served by the `packaged version`_ available at
SourceForge. You can also install Leo manually, as discussed in the
`next slide`_.

**Installing Leo from sources**

See the `next slide`_.
#@+node:ekr.20101128120258.5087: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\installation\_build\html\slide-001.html
#@+node:ekr.20100821182153.4348: *3* @slide Installing Leo from sources
.. _`Download Python`: http://www.python.org/download/
.. _`Leo's download page`: https://sourceforge.net/projects/leo/files/Leo/

**Installing Leo from sources**

1. Install Python: `Download Python`_, save to your desktop, then
   double-click on the saved file.

   Leo requires Python 2.6 or later, or Python 3.0 or later.

2. Install Qt. Get PyQt from: 
   http://www.riverbankcomputing.co.uk/software/pyqt/download

   The version of PyQt that you download must match the version of your Python.

3. Install Leo: Download the most recent .zip file from `Leo's
   download page`_ to your desktop or other location. Unzip the .zip
   file to the folder of your choice.
#@+node:ekr.20101128120258.5094: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\installation\_build\html\slide-002.html
#@+node:ekr.20101014034526.5302: *3* @slide Running Leo from a console
**Running Leo from a console**

To run Leo directly from a console, do the following:

1. Go to the Leo directory::

    cd <path-to-leo-directory>

2. Start launchLeo.py using Python::

    python launchLeo.py %*

#@+node:ekr.20101128120258.5089: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\installation\_build\html\slide-003.html
#@+node:ekr.20101014034526.5303: *3* @slide Scripts & .bat files
Using shell scripts (Linux) or .bat files (Windows)
can make it easier to open Leo files.

**Linux**

Put this in a shell script called leo::

    #!/bin/sh 
    python <path-to-leo-directory>launchLeo.py $1

**Windows**

Put this in leo.bat::

    cd <path-to-leo-folder>
    python <path-to-leo-folder>launchLeo.py %*

On either platform, the following will open x.leo::

    leo x.leo
#@+node:ekr.20101128120258.5090: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\installation\_build\html\slide-004.html
#@+node:ekr.20101014034526.5304: *3* @slide Setting .leoID.txt
The first time you start Leo, a dialog will ask you for a unique
identifier. This string helps ensure that each Leo node has a
unique identity.

This identifier can be any string 3 characters or more in length.
In a shared environment, a cvs or bzr login name works well.

Pick a string you don't mind making public: it will appear in
files that Leo creates.

Leo stores this identifier in the file ~/.leo/.leoID.txt.
You can change this identifier at any time by editing .leoID.txt.
#@+node:ekr.20101128120258.5091: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\installation\_build\html\slide-005.html
#@+node:ekr.20100821182153.4350: *3* @slide Free software
.. _`Edward K. Ream`:   ekr.html
.. _`leo-editor`:       http://groups.google.com/group/leo-editor
.. _`Python Tutorial`:  http://docs.python.org/tutorial/

Leo is a free program distributed under the MIT license. This means that not
only can you use the program freely including commercially, the full
installation comes with source code that you can modify as you wish, as long as
you give credit to the author of the program, `Edward K. Ream`_.

Leo is written in Python--a full featured, powerful programming language that
is comparatively easy to learn and use. For an excellent introduction to Python
for non-programmers, see the `Python Tutorial`_. Not only is Leo written in Python, it is
scriptable via Python, meaning that you can embed Python commands in your
outlines and execute them.

Leo is under active development and all are welcome to contribute. For more
information, see the `leo-editor`_ Google Group.

Not only is Leo free software, it is supported software. Post questions and bug
reports to the `leo-editor`_ Google Group.
#@+node:ekr.20101128120258.5096: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\installation\_build\html\slide-006.html
#@+node:ekr.20101013072903.5224: ** @slideshow Leo basics step by step
@pagewidth 50
#@+node:ekr.20101113202201.4920: *3* @wink_path = ../doc/html/slides/leo-basics-step-by-step/_files
@nocolor-node

The directory containing the wink screenshots.
This will usually be <slideshow_dir>/_files.

**Important** You generate these screenshots using Wink's 
Export As Html command (!)
#@+node:ekr.20101013072903.5225: *3* @slide ((no-slide
This is a step-by-step introduction to show you
how to use Leo outlines.

#@+node:ekr.20101018190057.5370: *4* @no-screenshot
#@+node:ekr.20101113211531.4918: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-001.html
#@+node:ekr.20101013072903.5226: *3* @slide ((Open notebook file
.. The workbook.leo window.

Leo opens the **workbook file** when you start
Leo without a filename.

The body has focus--it is colored a pale pink, and
contains a blinking cursor.

**Note**: on some monitors the colors will be almost
invisible.  You can choose pane colors to suit your
taste.

.. image:: slide-002.png

#@+node:ekr.20101018190057.5441: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-002.png
#@+node:ekr.20101113211531.4919: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-002.html
#@+node:ekr.20101014110348.5286: *3* @slide ((Ctrl-H edits headline
Ctrl-H edits the presently selected headline.

You can type Ctrl-H at any time, regardless of
where the focus is.

The body pane is now blue, indicating that it no
longer has focus.

.. image:: slide-003.png

#@+node:ekr.20101018190057.5442: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-003.png
#@+node:ekr.20101113211531.4920: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-003.html
#@+node:ekr.20101013072903.5234: *3* @slide (("to do" node
I typed "to do" in the headline.

.. image:: slide-004.png

#@+node:ekr.20101018190057.5443: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-004.png
#@+node:ekr.20101113211531.4921: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-004.html
#@+node:ekr.20101018061243.5392: *3* @slide ((Return ends editing
Typing the <return> key ends editing of the headline
and puts focus back in the body pane.

Notice that the **icon box** to the left of the
headline now has a darker outline that it had
before. This indicates that the contents of the
node has been changed. We say the node is
**dirty**.

.. image:: slide-005.png

#@+node:ekr.20101018190057.5444: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-005.png
#@+node:ekr.20101113211531.4922: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-005.html
#@+node:ekr.20101018061243.5393: *3* @slide ((no-slide focus keys
You can use Leo without ever using the mouse. For
instance, you can select any Leo pane by using
keystrokes instead of clicking the pane:

- Regardless of where the focus is, Alt-D puts
  focus in the body pane and Alt-T puts focus in
  the outline pane.

- With the focus in the tree pane, hitting the
  <return> key puts the focus in the body pane.

#@+node:ekr.20101018190057.5373: *4* @no-screenshot
#@+node:ekr.20101128120258.5093: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-006.html
#@+node:ekr.20101014110348.5325: *3* @slide ((Ctrl-S saves outline
Ctrl-S saves the outline.

Notice that the icon box once again has a gray outline,
indicating that the node has not been changed since
the file was last saved.

.. Arrow to icon box.

.. image:: slide-007.png

#@+node:ekr.20101018190057.5445: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-007.png
#@+node:ekr.20101113211531.4924: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-007.html
#@+node:ekr.20101013072903.5236: *3* @slide ((Ctrl-I inserts a new node
Ctrl-I inserts a new node.

.. image:: slide-008.png

#@+node:ekr.20101018190057.5446: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-008.png
#@+node:ekr.20101113211531.4925: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-008.html
#@+node:ekr.20101013072903.5237: *3* @slide (("go shopping"
I typed "go shopping" followed by a return.

The focus is now in the body pane.

.. image:: slide-009.png

#@+node:ekr.20101018190057.5447: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-009.png
#@+node:ekr.20101113211531.4926: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-009.html
#@+node:ekr.20101014110348.5305: *3* @slide ((typing text (icon box has blue square)
Whatever I type will appear in the body pane.

I added a shopping list.

The blue square in the icon area indicates that the body pane contains text.

.. Arrow at icon box.

.. buy milk
.. buy eggs.

.. image:: slide-010.png

#@+node:ekr.20101018190057.5448: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-010.png
#@+node:ekr.20101113211531.4927: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-010.html
#@+node:ekr.20101013072903.5244: *3* @slide ((Ctrl-R
Ctrl-R moves a node right.

The "go shopping" node becomes a **child**
of the "to do" node.

The "to do" node is the **parent** node.

.. image:: slide-011.png

#@+node:ekr.20101018190057.5449: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-011.png
#@+node:ekr.20101113211531.4928: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-011.html
#@+node:ekr.20101014110348.5290: *3* @slide ((Ctrl-L
Ctrl-L moves the "go shopping" node left.

The "go shopping" node becomes a **sibling**
of the "to do" node.

.. image:: slide-012.png

#@+node:ekr.20101018190057.5450: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-012.png
#@+node:ekr.20101113211531.4929: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-012.html
#@+node:ekr.20101013072903.5245: *3* @slide ((undo/redo
Leo has unlimited undo/redo capabilities.

Here, I typed Ctrl-Z to undo the previous move.
The "go shopping" node is once again a child of
the "to do" node.

**Note**: Ctrl-Shift-Z redoes a previous undo.

.. image:: slide-013.png

#@+node:ekr.20101018190057.5451: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-013.png
#@+node:ekr.20101113211531.4930: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-013.html
#@+node:ekr.20101014110348.5294: *3* @slide ((new node
Let's add a new node.  I hit Ctrl-I.

.. image:: slide-014.png

#@+node:ekr.20101018190057.5452: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-014.png
#@+node:ekr.20101113211531.4931: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-014.html
#@+node:ekr.20101014110348.5295: *3* @slide (("fix car"
I type "fix car" followed by the <return> key.

.. image:: slide-015.png

#@+node:ekr.20101018190057.5453: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-015.png
#@+node:ekr.20101113211531.4932: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-015.html
#@+node:ekr.20101014110348.5296: *3* @slide ((Ctrl-U
I decide that fixing the car should have first priority.

I type Ctrl-U to move the "fix car" node up.
It becomes the first child of the "to do" node.

.. image:: slide-016.png

#@+node:ekr.20101018190057.5454: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-016.png
#@+node:ekr.20101113211531.4933: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-016.html
#@+node:ekr.20101014110348.5297: *3* @slide ((contracting nodes
After creating the to-do list, I want to hide it
by **collapsing** the "to do" node.

I could do that by clicking the black triangle
to the left of the "to do" node.

However, using the mouse is not recommended--
there are much easier ways.

.. arrow points to black triangle.

.. image:: slide-017.png

#@+node:ekr.20101018190057.5455: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-017.png
#@+node:ekr.20101113211531.4934: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-017.html
#@+node:ekr.20101014110348.5298: *3* @slide ((Up-Arrow
The focus is in the tree pane, so I can select the "to do"
node merely by using the Up-Arrow key.

If, for some reason, the focus is in the body pane,
I can select the previous node in either of two ways:

1. Type Alt-T to put focus in the tree pane
   followed by the Up-Arrow key.

2. Type Alt-Up-Arrow.  This selects the previous
   node and also puts focus in the tree pane.

Now the "to do" node is selected.

.. image:: slide-018.png

#@+node:ekr.20101018190057.5456: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-018.png
#@+node:ekr.20101113211531.4935: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-018.html
#@+node:ekr.20101014110348.5299: *3* @slide ((Left-Arrow
With the "to-do" node selected,
hitting the Left-Arrow key will contract the node.

.. "to do" contracted.

.. image:: slide-019.png

#@+node:ekr.20101018190057.5457: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-019.png
#@+node:ekr.20101113211531.4936: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-019.html
#@+node:ekr.20101014110348.5300: *3* @slide ((20 Right-Arrow
To expand the "to do" node,
I merely hit the Right-Arrow key.

We can now see the entire to-do list.

.. image:: slide-020.png

#@+node:ekr.20101018190057.5458: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-020.png
#@+node:ekr.20101113211531.4937: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-020.html
#@+node:ekr.20101014110348.5309: *3* @slide ((no-slide Arrow keys: summary
The arrow keys do different things depending on
which pane has focus. Using arrow keys is **much**
easier than using the mouse.

**Focus in outline pane**

    The **plain** arrow keys **select** nodes,
    expanding or contracting nodes as needed.

    The **shift** arrow keys **move** nodes. The
    Shift-Left-Arrow and Shift-Up-Arrow contract
    nodes as needed. **Note**: the
    Shift-Down-Arrow and Shift-Right-Arrow keys
    never expand nodes.

**Focus in body pane**

    As usual, the **plain** arrow keys move the
    cursor and the **shift** arrow keys move the
    cursor and extend the solution.

    The **alt** arrow keys move the focus to the
    outline pane and then select nodes. The
    **alt-shift** arrow keys move the focus to the
    outline pane and then move nodes.

..  - The Up-Arrow and Down-Arrow keys select
..  the previous or next visible nodes.

..  - The Right-Arrow key contracts a node if the node
..  is expanded. Otherwise the Right-Arrow key
..  selects the node's parent.

..  - The Left-Arrow key does nothing if the selected
..  node has no children.  If the node does have
..  children, the Left-Arrow key expands the node
..  (if the children or invisible) or selects the
..  first child (if the children are visible).

..  This is exactly how Windows explorer works, and
..  it quickly becomes second nature.

#@+node:ekr.20101014110348.5323: *4* @no-screenshot
#@+node:ekr.20101113211531.4938: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-021.html
#@+node:ekr.20101014110348.5326: *3* @slide ((Shift-Ctrl-C copies
We can copy and paste nodes and all their descendants.

Using the arrow keys as necessary, I select the
"to do" node.

The Shift-Ctrl-C key copies the selected outline.

I want to do the paste *after* the to-do list, so I collapse
the original node before doing the paste:

.. image:: slide-022.png

#@+node:ekr.20101018190057.5459: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-022.png
#@+node:ekr.20101113211531.4939: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-022.html
#@+node:ekr.20101018061243.5397: *3* @slide ((The pasted node
And here is the pasted node.

.. image:: slide-023.png

#@+node:ekr.20101018190057.5460: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-023.png
#@+node:ekr.20101113211531.4940: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-023.html
#@+node:ekr.20101018061243.5394: *3* @slide ((expanding the pasted node
Expanding the node shows that the copy operation
copied the node and all its descendants.

.. image:: slide-024.png

#@+node:ekr.20101018190057.5461: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/leo-basics-step-by-step/slide-024.png
#@+node:ekr.20101113211531.4941: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-024.html
#@+node:ekr.20101014110348.5336: *3* @slide ((no-slide end slide
This concludes the step-by-step introduction to
Leo's outlines.

You now know how to do the following:

- Create new nodes.
- Edit the headline and body text of any node.
- Reorganize nodes. 
- Expand and contract nodes.
- Copy and paste nodes and their descendants.

Mastering these skills is essential to using Leo
effectively and enjoyably.

#@+node:ekr.20101018061243.5395: *4* @no-screenshot
#@+node:ekr.20101113211531.4942: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\leo-basics-step-by-step\_build\html\slide-025.html
#@+node:ekr.20101011165412.4968: ** @slideshow Scripting Leo
@pagewidth 50

.. This slideshow will have no screenshots.

#@+node:ekr.20101119112650.5363: *3* @slide Introduction
For me, scripting is the most fun part of Leo.

Leo can execute any body text as a **Leo script**,
Python scripts that have full access to all data
in any open Leo outline, as well as full access to
all parts of Leo's source code.

Leo's Ctrl-B (execute-script) command runs the
body text of a node as a Leo script.
#@+node:ekr.20101121125326.4962: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\scripting-leo\_build\html\slide-001.html
#@+node:ekr.20101119112650.5368: *3* @slide c, g and p
.. _`Scripting Chapter`: tutorial-scripting.html
.. _`Leo's Users Guide`: leo_toc.html

Leo scripts execute in an environment containing
three predefined objects: c, g and p.

**g** is Leo's leoGlobals module. This module
contains several dozen utility functions and
classes.

**c** is the **commander** of the outline
containing the script. Commanders defined
all of Leo's commands, as well as other data.

**p** is the **position** of the presently
selected node. Positions represent positions
in the traversal of Leo outlines.

This slide give a few examples of how to use
c, g and p in Leo scripts. For full details
about scripting in Leo, see the `Scripting Chapter`_
in `Leo's Users Guide`_.
#@+node:ekr.20101121125326.4963: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\scripting-leo\_build\html\slide-002.html
#@+node:ekr.20101119112650.5369: *3* @slide Official ivars
The c, g and p objects give Leo scripts access to
all parts of Leo and Leo outlines. There are many
**official ivars** (instance variables) that
scripts may use. Here are a few:

**c.frame** is the frame representing the actual
parts of Leo screen. For any frame, **frame.c** is
the frame's commander, so c.frame.c is always c.

**g.app** is the **application object**
representing the entire Leo application. The ivars
of g.app represent Leo's global variables.

**p.v** is the **vnode** at position p. A vnode
represents an outline node. Vnodes hold most of
the data in Leo outlines. For any vnode v, v.h is
the node's headline, and v.b is the node's body
text. As a convenience, for any position p, p.h
and p.b are synonyms for p.v.h and p.v.b.
**Important**: because of clones, a vnode may
appear in several positions in a traversal.
#@+node:ekr.20101121125326.4964: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\scripting-leo\_build\html\slide-003.html
#@+node:ekr.20101119112650.5374: *3* @slide Hello world
g.es is a function that prints its arguments to Leo's log pane.

Here is the hello world program as a Leo script::

    g.es('Hello world!')

Leo scripts may also use Python's print command
provided that Leo is running in a console.
#@+node:ekr.20101121125326.4965: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\scripting-leo\_build\html\slide-004.html
#@+node:ekr.20101119112650.5371: *3* @slide p.h and p.b
.. _`Python properties`: http://docs.python.org/library/functions.html

Given any position p, **p.h** is the headline text
of p.v, and **p.b** is the body text of p.v.

p.h and p.b are `Python properties`_, which means
you can set the headline and body text by
assigning to them::

    p.h = p.h + ' more'

In order to see the result of changing a headline,
Leo scripts must redraw the outline pane, like this::

    c.redraw()
#@+node:ekr.20101121125326.4966: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\scripting-leo\_build\html\slide-005.html
#@+node:ekr.20101119112650.5375: *3* @slide Iterators
.. _`Python iterator`: http://docs.python.org/library/stdtypes.html#iterator-types

Commanders and positions define `Python
iterators`_ that return lists of positions in Leo
outlines. These iterators are the easiest way of
gaining access to the nodes of Leo outlines. Here
are few examples (there are many more):

- **c.all_positions()** returns all the positions
  of the outline in order. Cloned nodes will
  appear several times in this list.

- **c.all_unique_nodes()** returns all the vnodes
  of the outline.

- **p.self_and_subtree()** returns p and all its
  descendant positions.

- **p.children()** returns all the positions of
  all p's direct children.
#@+node:ekr.20101121125326.4967: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\scripting-leo\_build\html\slide-006.html
#@+node:ekr.20101121021109.5351: *3* @slide Using iterators
Using iterators, it is easy to gain access to all the data in a Leo outline. For example, the following script prints all headlines in an outline, indented to show outline level::

    for p in c.all_positions():
        print(' '*p.level(), p.h)

The output of this script, when run from LeoDocs.leo,
will look something like this::

    Startup
     @file doc-startup.txt
      Buttons
       Disabled buttons
       ... and hundreds of other nodes.

**Note**: p.level() is a method of the position class that returns the outline level of the node at position p: 0 for top-level nodes, 1 for their children, and so on.

**Note**: There are performance problems when writing many strings to Leo's log pane. The following will hang Leo when run within large .leo files:

    for p in c.all_positions():
        g.es(' '*p.level(), p.h)
        
The workaround is to precompute a single string, and pass it to c.frame.log.put:

    s = ''.join([
        '%s%s\n' % (' '*p.level(), p.h) for p in c.all_positions()
    ])
    c.frame.log.put(s)
#@+node:ekr.20101121125326.4968: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\scripting-leo\_build\html\slide-007.html
#@+node:ekr.20101119112650.5370: *3* @slide Building scripts from outlines
Leo scripts can be composed of more than one node,
just as external files are organized. The Execute
Script command **preprocesses** the script before
executing it, by expanding section references and
\@others directives

For example, I organize my complex script as follows.
I create a top-level node containing just::

    '''docstring'''
    @others
    controller(c).run()

A child node will contain the following::

    class controller:
        def __init__(self,c):
            self.c = c
        @others

And the children of the top-level class node will
contain all the methods of the controller class.
This organization is simple, flexible and powerful.
#@+node:ekr.20101121125326.4969: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\scripting-leo\_build\html\slide-008.html
#@+node:ekr.20101119112650.5376: *3* @slide g.openWithFileName
The c and g constants give you access to all of
Leo's source code. Here, we'll discuss just two of
them. There are hundreds more you can use.

**g.openWithFileName** opens a .leo file.  For example::

    ok, frame = g.openWithFileName(fileName,c)
    new_c = frame.c

The return frame value represents the frame of the visual
outline.  frame.c is the frame's commander, so new_c is
the commander of the newly-created outline.

#@+node:ekr.20101119112650.5381: *4* @no-screenshot
#@+node:ekr.20101121125326.4970: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\scripting-leo\_build\html\slide-009.html
#@+node:ekr.20101119112650.5377: *3* @slide g.pdb
.. _`Python debugger`: http://docs.python.org/library/pdb.html
.. _`Pudb debugger`: http://pypi.python.org/pypi/pudb

**g.pdb** opens pdb, the `Python debugger`_.  To use this,
you must be running Leo from a console.

The pudb plugin changes g.pdb so that it uses the
full-screen `Pudb debugger`_ instead of pdb.
#@+node:ekr.20101119112650.5379: *4* @no-screenshot
#@+node:ekr.20101121130516.4962: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\scripting-leo\_build\html\slide-010.html
#@+node:ekr.20101121021109.5352: *3* @slide Further reading
.. _`Scripting Chapter`: tutorial-scripting.html
.. _`Leo's Users Guide`: leo_toc.html

This concludes our brief introduction to scripting in Leo.

For full details about scripting in Leo, see the
`Scripting Chapter`_ in `Leo's Users Guide`_.
#@+node:ekr.20101121125326.4972: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\scripting-leo\_build\html\slide-011.html
#@+node:ekr.20101014034526.5296: ** @slideshow Using Leo's minibuffer
@pagewidth 60
#@+node:ekr.20101122071746.5047: *3* @wink_path = ../doc/html/slides/using-leos-minibuffer/_files
#@+node:ekr.20101122071746.4988: *3* @slide Introduction
Leo's **minibuffer** appears at the bottom of Leo's main window.

You use the minibuffer to execute commands by name, and also
to accumulate arguments to commands.

Type <Alt-x> to put the cursor in the minibuffer.

.. sc 1: cursor in the minibuffer

.. image:: slide-001.png

#@+node:ekr.20101123095350.5005: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/using-leos-minibuffer/slide-001.png
#@+node:ekr.20101123095813.5004: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\using-leos-minibuffer\_build\html\slide-001.html
#@+node:ekr.20101122071746.4990: *3* @slide Tab completion
You could type the full command name in the minibuffer,
followed by the <return> key to invoke the command,
but that would be **way** too much work.

Instead, you can use **tab completion** to avoid having to
do much typing. With tab completion, there is no need to
remember the exact names of Leo's commands.

.. no screenshot
#@+node:ekr.20101122071746.5004: *4* @no-screenshot
#@+node:ekr.20101122071746.4992: *3* @slide Example
For example, suppose you want to print out the list of Leo's
commands. You might remember only that there are several
related commands and that they all start with "print".
Just type::

    <alt-x>pri<tab>

You will see "print-" in the minibuffer.
The **Completion tab** in the log pane shows
all the commands that start with "print-".

.. sc 2: The Completion tab contains print- items

.. image:: slide-003.png

#@+node:ekr.20101123095350.5006: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/using-leos-minibuffer/slide-003.png
#@+node:ekr.20101123095813.5006: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\using-leos-minibuffer\_build\html\slide-003.html
#@+node:ekr.20101122071746.5005: *3* @slide Example, continued
Now just type "c<tab>" and you will see one the single
print-commands command in the minibuffer. Finally, type
<return> to execute the command.

.. sc 3:  Only the print-commands command in the Completion tab.

.. image:: slide-004.png

#@+node:ekr.20101123095350.5007: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/using-leos-minibuffer/slide-004.png
#@+node:ekr.20101123095813.5007: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\using-leos-minibuffer\_build\html\slide-004.html
#@+node:ekr.20101122071746.5006: *3* @slide Example, concluded
You will see the output of the print-commands command
in the commands tab, and focus returns to the body pane.

.. sc 4: show the Commands tab.

.. image:: slide-005.png

#@+node:ekr.20101123095350.5008: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/using-leos-minibuffer/slide-005.png
#@+node:ekr.20101123095813.5008: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\using-leos-minibuffer\_build\html\slide-005.html
#@+node:ekr.20101122071746.4994: *3* @slide Details
Using the minibuffer quickly becomes second nature. When in
doubt about what the valid completions are, you simply hit
the <tab> key.

Here are a few more details you should know about:

- You can use <BackSpace> in the minibuffer to show more
  alternatives.

- You can hit <Ctrl-G> at any time in Leo to put focus in
  the body pane.  This is the way to exit the minibuffer
  without executing any command.

.. no screenshot
#@+node:ekr.20101122071746.5045: *4* @no-screenshot
#@+node:ekr.20101122071746.5007: *3* @slide Arguments
Several of Leo's commands use the minibuffer to get arguments.

For example, Leo's find command accumulates the search and
replace strings in the minibuffer.

To invoke the find command, type <Ctrl-F>. This puts the
focus in the minibuffer and shows the Find tab.
**Important**: the Find tab just shows you the status of
search and replace operations. You control those operations
from the minibuffer.

.. sc 5  (missing the cursor)

.. image:: slide-007.png

#@+node:ekr.20101123095350.5009: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/using-leos-minibuffer/slide-007.png
#@+node:ekr.20101123095813.5012: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\using-leos-minibuffer\_build\html\slide-007.html
#@+node:ekr.20101122071746.5021: *3* @slide Search string
Now type the search string, say "def".

.. sc 6: searching for "def".

.. image:: slide-008.png

#@+node:ekr.20101123095350.5010: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/using-leos-minibuffer/slide-008.png
#@+node:ekr.20101123095813.5013: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\using-leos-minibuffer\_build\html\slide-008.html
#@+node:ekr.20101122071746.5008: *3* @slide Replace string
You can invoke the find by typing <return>.

However, suppose you want to replace "def" with "foo".

Type <Shift-Ctrl-R>. The minibuffer prompts for the replacement string.
Notice that the status area now shows "def" as the Find string.

.. sc 7: Replace String: def With:

.. image:: slide-009.png

#@+node:ekr.20101123095350.5011: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/using-leos-minibuffer/slide-009.png
#@+node:ekr.20101123095813.5016: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\using-leos-minibuffer\_build\html\slide-009.html
#@+node:ekr.20101122071746.5009: *3* @slide Doing the find
Type "foo" and hit return to start the find-next command.

.. sc 8 show "def" selected.

.. image:: slide-010.png

#@+node:ekr.20101123095350.5012: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/using-leos-minibuffer/slide-010.png
#@+node:ekr.20101123095813.5019: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\using-leos-minibuffer\_build\html\slide-010.html
#@+node:ekr.20101122071746.5010: *3* @slide Doing the replace
Here, Leo has found the next instance of "def" in the body pane.

- To make the replacement, hit <Ctrl-minus>.

- To continue searching without making a replacement, hit <F3>.

- To end the search, hit <Ctrl-G>.

This concludes the discussion of the minibuffer.

.. image:: slide-011.png
#@+node:ekr.20101123095350.5013: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/using-leos-minibuffer/slide-011.png
#@+node:ekr.20101123095813.5018: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\using-leos-minibuffer\_build\html\slide-011.html
#@+node:ekr.20101014110348.5293: ** @slideshow Clones and views
@pagewidth 60
#@+node:ekr.20101123095813.5044: *3* @wink_path ../doc/html/slides/clones-and-views/sc_files
#@+node:ekr.20101122052247.4962: *3* @slide Clones and views
Clones are one of Leo's most unusual and most useful features.

A **clone** is a node that appears in more than one place in a Leo outline.

Here, we have cloned node A by selecting A and doing Ctrl=` (clone-node)

Clones are marked with a small red *clone arrow** in the icon box.
Deleting the penultimate clone removes the red arrow from the node.

.. sc 1: Clone of A.

.. image:: slide-001.png

#@+node:ekr.20101123095813.5046: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/clones-and-views/slide-001.png
#@+node:ekr.20101123095813.5056: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\clones-and-views\_build\html\slide-001.html
#@+node:ekr.20101122052247.4964: *3* @slide Clones are the same node
Changing the headline or body text of a clone changes the headline or body
text of all other clones of that node. Furthermore, changing any descendants
of a clone, including inserting, deleting or moving nodes, results in the
same changes being made to all other clones.

In fact, all clones of a node are actually *the exactly the same node*, so
any change to one clone inevitably affects all other clones.

.. no sc
#@+node:ekr.20101122052247.4979: *4* @no-screenshot
#@+node:ekr.20101123095813.5062: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\clones-and-views\_build\html\slide-002.html
#@+node:ekr.20101122052247.4966: *3* @slide Changing headlines
Changing the headline of node A changes the headlines of all cloned nodes.

.. sc 2: Rename the node to B.

.. image:: slide-003.png

#@+node:ekr.20101123095813.5047: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/clones-and-views/slide-003.png
#@+node:ekr.20101123095813.5057: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\clones-and-views\_build\html\slide-003.html
#@+node:ekr.20101122052247.4968: *3* @slide A new node
Here we have created a node C following the first clone of B.

.. sc 3: Create node C

.. image:: slide-004.png

#@+node:ekr.20101123095813.5048: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/clones-and-views/slide-004.png
#@+node:ekr.20101123095813.5058: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\clones-and-views\_build\html\slide-004.html
#@+node:ekr.20101122052247.4970: *3* @slide Adding a child node
Moving C to the right makes C a child of node B.
As you can see, C appears as a child of both cloned nodes.

Even the expansion state of cloned nodes are identical:
both clones are now expanded.

.. sc 4: move C right.

.. image:: slide-005.png

#@+node:ekr.20101123095813.5049: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/clones-and-views/slide-005.png
#@+node:ekr.20101123095813.5059: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\clones-and-views\_build\html\slide-005.html
#@+node:ekr.20101122052247.4972: *3* @slide Creating a new child
Here, I have created a new node D with Ctrl-I (insert-node).

The node appears as a child of both cloned nodes.

In general, **any** change to one clone produces the
corresponding change in all other clones.

.. sc 5: Insert node

.. image:: slide-006.png

#@+node:ekr.20101123095813.5050: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/clones-and-views/slide-006.png
#@+node:ekr.20101123095813.5060: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\clones-and-views\_build\html\slide-006.html
#@+node:ekr.20101122052247.4974: *3* @slide Keeping track of changes
Changing a node marks all clones of that node as changed.
When I save the Leo outline, Leo automatically writes all
the external files that contain dirty nodes.

For example, the cloned spam node appears in two places.

.. sc 6: @file node is dirty

.. image:: slide-007.png

#@+node:ekr.20101123095813.5051: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/clones-and-views/slide-007.png
#@+node:ekr.20101123095813.5061: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\clones-and-views\_build\html\slide-007.html
#@+node:ekr.20101123095813.5042: *3* @slide Keeping track of changes: 2
Changing either clone marks both as changed and marks any
ancestor @file nodes as changed as well.

This ensures that saving the .leo file will also save all
changed external files.

.. sc 7: @file node is dirty

.. image:: slide-008.png

#@+node:ekr.20101123095813.5052: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/clones-and-views/slide-008.png
#@+node:ekr.20101123095813.5063: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\clones-and-views\_build\html\slide-008.html
#@+node:ekr.20101122052247.4976: *3* @slide Views
Clones are important because they allow you to create as
many views of the data in the outline as you like. In
effect, Leo becomes a supremely flexible filing cabinet. Any
ordinary node can act like a folder in the filing cabinet.
Using clones, you can "file" a node in as many folders as
you like.

.. no sc
#@+node:ekr.20101123095813.5045: *4* @no-screenshot
#@+node:ekr.20101123095813.5064: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\clones-and-views\_build\html\slide-009.html
#@+node:ekr.20101123095813.5039: *3* @slide Views: 2
In Leo, a **view** is simply a subset of the nodes of the
outline. We represent a view as **ordinary** node, called a
**view node** (1). The children of the view node are the subset of
nodes that define the view. It's that simple.

With Leo, you can have as many view nodes as you like. There
is no such thing as a single, "correct" view of data.

.. sc 8: Ordinary node with clones.

.. image:: slide-010.png

#@+node:ekr.20101123095813.5053: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/clones-and-views/slide-010.png
#@+node:ekr.20101123095813.5065: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\clones-and-views\_build\html\slide-010.html
#@+node:ekr.20101122052247.4978: *3* @slide Bug nodes
I use view nodes to focus attention on a set of disparate
nodes. For example, when I fix a bug in Leo, I create a **bug
node** containing all the data in Leo's source code that
relates to the bug. As I discover code related to the bug, I
clone nodes and move them under the bug node. I'll also add
ordinary nodes as children of the bug node. These nodes
contain the original bug report, descriptions of how I fixed
the bug, test data, or any other notes I might want to keep.

.. sc 9: bug node

.. image:: slide-011.png

#@+node:ekr.20101123095813.5054: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/clones-and-views/slide-011.png
#@+node:ekr.20101123095813.5066: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\clones-and-views\_build\html\slide-011.html
#@+node:ekr.20101123095813.5040: *3* @slide Bug nodes: 2
Once I have created the bug node, I concentrate *only* on
that node and its children. I can examine the bug node and
its children without having to jump around the outline.
Everything I need is in one place. This extremely narrow
focus makes it *much* easier to fix bugs. to jump around the
outline. It doesn't matter how big or complex the outline
is: I am only dealing with the bug node and its children.

**Important**: I can fix the bug by changing the clones in
the view node. When I save the Leo file, Leo will save all
the @<file> nodes that contain any changed clone. Everything
"just works".

.. no screenshot
#@+node:ekr.20101123095813.5043: *4* @no-screenshot
#@+node:ekr.20101123095813.5067: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\clones-and-views\_build\html\slide-012.html
#@+node:ekr.20101014034526.5280: ** @slideshow External files
@pagewidth 60
#@+node:ekr.20101123095813.5072: *3* @wink_path = ../doc/html/slides/external-files/_files
#@+node:ekr.20101122052247.4980: *3* @slide External files
Trees whose root headline starts with \@file, \@auto or
\@edit create **external files** on your file system. Here
are some example headlines::

  @file myClass.py
  @auto ../graphics/circles.cpp
  @edit ~/.leo/.leoID.txt

As you can see, these nodes specify file names, which can be
an absolute path or a path relative to the directory
containing the Leo outline.

Collectively, nodes that create external files are known as
**@<file> nodes.** Leo defines several other kinds of
@<file> nodes, but this slideshow will not discuss them.

.. no sc


#@+node:ekr.20101123095813.5020: *4* @no-screenshot
#@+node:ekr.20101123095813.5104: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-001.html
#@+node:ekr.20101122052247.4982: *3* @slide Loading and saving files
Leo automatically loads all @<file> trees when you open a
Leo outline, and Leo writes any modified @<file> tree when
you save an outline. Reading external files is very fast
because of an efficient file-caching scheme.

A single Leo outline may be connected to dozens of external files: this
makes Leo work like an Integrated Development Environment (IDE). Leo
outlines act like project files. For example, one Leo outline,
leoPyRef.leo, contains \@file trees for all of Leo's core and plugins
files, while LeoDocs.leo contains all of Leo's documentation.

#@+node:ekr.20101123095813.5021: *4* @no-screenshot
#@+node:ekr.20101123095813.5105: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-002.html
#@+node:ekr.20101122052247.4984: *3* @slide Sentinel lines
Leo stores the structure of \@file trees in external files
themselves using comment lines called **sentinel lines**.
Sentinel lines allow Leo to keep track of outlines
structure, including clone relationships. Using \@file is
**highly recommended** whenever possible. In particular,
using \@file allows you to **share outline structure** with
others merely by sharing external files. External files
created from \@file nodes contain **all** essential data:
The .leo file contains only the headline of the \@file node.
All the data resides in the external files.

.. no sc
#@+node:ekr.20101123095813.5023: *4* @no-screenshot
#@+node:ekr.20101123095813.5106: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-003.html
#@+node:ekr.20101123095813.5068: *3* @slide Avoiding sentinels
In some situations it is not appropriate to use sentinel
comments in external files. In that case you use \@auto and
\@edit trees to connect Leo outlines to existing external
files without creating sentinel files. Not all of Leo's
features can be used with \@auto and \@edit trees, but that
can't be helped. In particular, Leo can not preserve outline
structure exactly. Leo's "degraded" operation for such trees
is similar to that found in all other editors and IDE's.

The rest of this slide show will discuss \@file trees and
their capabilities. We will then discuss \@auto and \@edit.

.. no sc
#@+node:ekr.20101123095813.5070: *4* @no-screenshot
#@+node:ekr.20101123095813.5107: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-004.html
#@+node:ekr.20101122052247.4986: *3* @slide Using @file trees
To repeat, it's best to use \@file to create external files
if at all possible. The next series of slides will show you
how to create external files with \@file trees.

To create a new external file, create an \@file node giving
the path to the external file. This path can be a full,
absolute path, but usually it is more convenient to use a
relative path. All relative paths in @<file> nodes are
relative to Leo's **load directory**, the directory
containing the .leo file for the present outline. In most
cases, we can ignore the path prefix entirely.

.. sc 1: @file myFile.py

.. image:: slide-005.png

#@+node:ekr.20101123095813.5074: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/external-files/slide-005.png
#@+node:ekr.20101123095813.5087: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-005.html
#@+node:ekr.20101122052247.4988: *3* @slide Top-level design pattern
The body text of the @file node contains typical code for a
file that defines a single Python class. Informally, it says
that external file consists of import statements, followed
by the class MyDemoClass.

The next few slides will discuss this pattern line-by-line.

.. sc 2: top-level node
..  << imports >>
..  class MyDemoClass:
..      @others

.. image:: slide-006.png

#@+node:ekr.20101123095813.5075: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/external-files/slide-006.png
#@+node:ekr.20101123095813.5089: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-006.html
#@+node:ekr.20101122052247.4990: *3* @slide Section references
The << imports >> line is a **section reference**. "Imports"
is the **section name**. This line tells Leo to insert the
**section definition** into the output file at the place
where section reference occurs.

.. sc 3: top-level node (with imports line highlighted)

.. image:: slide-007.png

#@+node:ekr.20101123095813.5076: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/external-files/slide-007.png
#@+node:ekr.20101123095813.5090: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-007.html
#@+node:ekr.20101122052247.4992: *3* @slide Section definitions
**Section definition nodes** create section definitions.
Section definition nodes contain a section name in the
headline. The body text contains the section definition.

Therefore, the definition of << imports >> are the lines::

    import os
    import sys

Each section definition node must be a descendant of the
node containing the section reference.

.. sc 4: << imports node >>

.. image:: slide-008.png

#@+node:ekr.20101123095813.5077: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/external-files/slide-008.png
#@+node:ekr.20101123095813.5091: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-008.html
#@+node:ekr.20101122052247.4994: *3* @slide The @others directive
The **@others directive** is similar to a section reference;
\@others tells Leo to insert text into the output file.
Instead of inserting the body text of one particular node,
as in a section reference, \@others tells Leo to insert the
body text of all nodes that **aren't** section definition
nodes. That's where the name comes from: it inserts all the
**other** nodes.

.. sc 5: top-level node (with @others line highlighted)

.. image:: slide-009.png

#@+node:ekr.20101123095813.5078: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/external-files/slide-009.png
#@+node:ekr.20101128120258.5095: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-009.html
#@+node:ekr.20101123095813.5025: *3* @slide References & expansions
Let us use the term **reference** to mean either a section
reference or an \@others directive. The **expansion** of a
reference is the set of all lines that Leo writes to the
output file as the result of that reference.

.. no sc
#@+node:ekr.20101123095813.5026: *4* @no-screenshot
#@+node:ekr.20101123095813.5108: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-010.html
#@+node:ekr.20101122052247.4998: *3* @slide Indentation
The indentation of references is significant. Leo indents
each line of the expansion of a reference by the total
amount of leading whitespace that is in effect at the point
of the reference. This allows Leo to handle languages like
Python in which indentation is especially important.

In our example, there is no leading whitespace before the
reference to << imports >>, but there are four spaces before
the \@others directives. This means that Leo writes the
import statements without additional indentation, but Leo
adds 4 spaces before all nodes written as the result of the
\@others directive.

.. sc 7: highlight indentation of @others

.. image:: slide-012.png

#@+node:ekr.20101123095813.5080: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/external-files/slide-012.png
#@+node:ekr.20101128120258.5097: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-011.html
#@+node:ekr.20101123095813.5024: *3* @slide Indentation, 2
Indentation is controlled **only** by the
indentation of references. The outline level of nodes in
expansions does not affect indentation in any way.

This **decoupling** of outline structure from indentation is
very important: it allows you to create **organizer nodes**
without affecting the external file in any significant way
(other than sentinel comments).

.. no sc
#@+node:ekr.20101123095813.5029: *4* @no-screenshot
#@+node:ekr.20101123095813.5109: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-012.html
#@+node:ekr.20101122052247.5000: *3* @slide Expansions: 2
Any node may contain one or more section references, and any
node may also contain a single \@others directive.

A. The expansion of a section reference is just exactly the
   expansion of the body of the section definition node.
   That expansion may include expansions of *other*
   references appearing in that node.

B. The expansion of an @others directive is the expansion of
   all descendant nodes that aren't section definition nodes
   and are not included in the expansion of \@others nodes
   deeper in the tree. This means that no node is ever
   included in the expansion of more than one \@other
   directive. Non-section-definition nodes are included in
   the expansion of the nearest \@others directive.

.. no sc
#@+node:ekr.20101123095813.5033: *4* @no-screenshot
#@+node:ekr.20101123095813.5110: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-013.html
#@+node:ekr.20101122052247.5013: *3* @slide Orphan nodes
Each node in an \@file tree, except the \@file node itself,
must be part of the expansion of exactly one reference. When
writing an external file, Leo makes the following checks:

1. Each section must be defined. There must be a section
   reference in an ancestor of each section definition node.

2. There must be no **orphan nodes**.  A section definition node is an
   orphan if no ancestor node contains a reference to that node.
   A non-definition node is an orphan if no ancestor node contains an
   \@others directive.

Leo will issue an error if these checks are not satisfied.

.. no sc
#@+node:ekr.20101123095813.5035: *4* @no-screenshot
#@+node:ekr.20101123095813.5111: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-014.html
#@+node:ekr.20101122052247.5002: *3* @slide Using multiple @others nodes
Here is a common pattern for a file that defines two
classes, SpamClass and EggsClass. The top-level node
includes imports, and then uses \@others to include the
expansion of the rest of the outline.

.. sc 8: only @others at the top level.
..  << imports >>
..  @others
..  ======== children
..    SpamClass
..      @others
..    EggsClass
..      @others

.. image:: slide-016.png

#@+node:ekr.20101123095813.5081: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/external-files/slide-016.png
#@+node:ekr.20101123095813.5098: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-015.html
#@+node:ekr.20101122052247.5004: *3* @slide SpamClass
The first child node creates the expansion of SpamClass. The
lines::

    class SpamClass:
        '''A class representing spam.'''

have no extra indentation, because the \@others in the
top-level node has no leading whitespace.

However, the two methods of the class will have 4 spaces of
indentation because the \@others directive in *this* node is
indented by 4 spaces.

.. sc 9: SpamClass

.. image:: slide-017.png

#@+node:ekr.20101123095813.5082: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/external-files/slide-017.png
#@+node:ekr.20101123095813.5099: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-016.html
#@+node:ekr.20101122052247.5006: *3* @slide EggsClass
The second child node creates the expansion of EggsClass in
a similar manner. It's always perfectly clear what nodes are
included in \@others directives. \@others refers to all
descendant nodes of *this* node.

.. sc 10: EggsClass

.. image:: slide-018.png

#@+node:ekr.20101123095813.5083: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/external-files/slide-018.png
#@+node:ekr.20101123095813.5100: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-017.html
#@+node:ekr.20101122052247.5008: *3* @slide Using @others to group code
You can use \@others to "comment out" all descendant nodes as
shown. This works in Python because the indentation of the
\@others directive causes the expansion of all descendant
nodes to have 4 extra spaces.

.. sc 11:
..  if 0:
..      @others

.. image:: slide-019.png

#@+node:ekr.20101123095813.5084: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/external-files/slide-019.png
#@+node:ekr.20101123095813.5101: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-018.html
#@+node:ekr.20101123095813.5036: *3* @slide Summary of @file
This concludes our brief discussion of \@file nodes. The next
few slides discuss two alternatives to \@file, \@auto and
\@edit.

\@auto and \@edit create external files without sentinel
lines. The cost of avoiding sentinel lines is that Leo can
not preserve outline structure exactly.

.. no sc
#@+node:ekr.20101123095813.5037: *4* @no-screenshot
#@+node:ekr.20101123095813.5112: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-019.html
#@+node:ekr.20101122052247.5010: *3* @slide Using @auto nodes
When Leo reads an **@auto node**, Leo will automatically
create an outline that shows the class, functions or other
units of the external file.

Leo can only do this if Leo has an **importer** for the
external file. At present, Leo has importers for C, elisp,
HTML, .ini files, Java, Javascript, Pascal, PHP, Python and
xml. Leo determines the language using the file's extension.
If no parser exists for a language, Leo copies the entire
body of the external file into the \@auto node.

.. no sc
#@+node:ekr.20101123095813.5073: *4* @no-screenshot
#@+node:ekr.20101123095813.5113: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-020.html
#@+node:ekr.20101123095813.5038: *3* @slide @auto example
Here is an example of an actual Python file imported into Leo.

The importer has created the entire outline, including
the body text of the root \@auto node.

The importer created an \@others directive (1) to place the
expansion of the descendant nodes properly, before the
final top-level lines of the file (2).

.. sc 12: Showing tree of nodes imported by @auto

.. image:: slide-022.png

#@+node:ekr.20101123095813.5085: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/external-files/slide-022.png
#@+node:ekr.20101123095813.5102: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-021.html
#@+node:ekr.20101122052247.5012: *3* @slide Using @edit nodes
When Leo reads and **@edit node**, Leo reads the entire
contents of the external file into the body text of the
\@edit node. Any changes to the external file will appear in
the \@edit node the next time Leo loads the external file.
Rather than creating new files with @edit, it is more common
to use @edit to connect Leo with files that already exist on
your file system.

.. sc 13: Showing @edit node.

.. image:: slide-023.png

#@+node:ekr.20101123095813.5086: *4* @url final output file
c:/leo.repo/leo-editor/leo/doc/html/slides/external-files/slide-023.png
#@+node:ekr.20101123095813.5103: *4* @url built slide
c:\leo.repo\leo-editor\leo\doc\html\slides\external-files\_build\html\slide-022.html
#@-all
#@-leo
