Thanks. It's good to be understood. I agree that clones are a key feature of Leo. Clones work in Leo exactly as they did in the old MORE editor on the Mac.
I am the creator of Leo. Your comments are not inflamatory, they are simply wrong. It is a gross violation of common courtesy to pontificate about that which you know next to nothing.
A lot of people seem to feel qualified to comment about Leo after just reading the original slashdot article. Most have no clue about what Leo is or isn't. I've spent seven years working on Leo. I'm getting pretty annoyed about people commenting about Leo without even taking seven minutes to play with it.
Leo really isn't all that much about either literate programming or documentation; it's about structure and clarity. I explain what Leo is in my posting, "The creator's view of Leo."
A lot of people seem to feel qualified to comment about Leo after just reading the original slashdot article. Most have no clue about what Leo is or isn't. I've spent seven years working on Leo. I'm getting pretty annoyed about people commenting about Leo without even taking seven minutes to play with it.
Leo really isn't all that much about either literate programming or documentation. I explain what Leo is in my posting, "The creator's view of Leo."
The pros and cons of documentation, inline or not, are not really relevant to what Leo is about.
Please read my posting, "The creator's view of Leo".
- Edward K. Ream
Hi. I am the creator of Leo and I'd like to say here what my own view of Leo is. Joe Orr has contributed greatly to Leo, and I would not characterize Leo exactly as he did in his original article. In this posting I hope to clear up misconceptions about what Leo is, what it can do, and the relationship of Leo to literate programming.
I would like to distinguish between the techniques of literate programming and the practice of literate programming (LP) as it has always been done before Leo (traditional LP). The key technique of LP is what might be called "functional pseudocode." For example, here is a fragment of code that can be written in Leo:
def spam():
done = false ; result = None
while not done:
<< do something complicated >>
return result
The line: << do something complicated >> is a section reference. It works pretty much like a macro call. In particular, the code in the defintion of << do something complicated >> has access to the done and result variables. This is almost the entire content of noweb, one form of literate programming. It turns out that this technique can be extremely useful, as simple as it seems. Leo creates one or more "derived" files from an outline automatically when the outline is written, and Leo can update the outline from changes made to derived files when Leo reads the outline.
In contrast to the technique of literate programming, the practice of traditional LP has focused on the central role of comments, and lots of them. Here is where Leo radically parts company with the LP tradition.
One's view of the proper role of documentation in a project hardly matters to Leo. You are free to use comments as you always did, though you will probably find that LP as implemented in Leo helps you out in unexpected ways. I discuss at length and in great detail the relationship between traditional LP, comments and Leo here. In short, discussions about the role of comments in programming (literate or not) do not get to the heart of Leo.
In fact, Leo often reduces the need for comments. Indeed, it is good style to organize Leo outlines like a reference book. Well-designed Leo outlines act both like self-updating tables of contents and self-updating indices. This is in marked contrast to the "stream-of-consciousness" or "narrative" style typically employed in traditional literate programming.
In my view, the essence of Leo is this: Leo makes outline organization the most important part of a program or a project. Both code and documentation could be considered secondary. At every moment, the overall big picture of a function, class, module, file or project is always at hand. Moreover, Leo makes outlines structure a part of the computer language. For example, I often define a Python class as follows:
class myClass:
<< declarations of myClass >>
@others
The @others directive acts as a reference to all the text in all the outline nodes which are descendents of the node containing this class declaration. Such nodes are copied to the output (derived) file in the order in which they appear in the outline. The reference << declarations of myClass >> ensures that those declarations precede the methods. There are several other ways that outline structure is important in Leo; I won't discuss them here.
Leo fully exploits the organizational power of outlines. A single outline typically organizes an entire project. Outlines can handle large amounts of data with ease. Moreover, it is possible to clone any part of an outline so that changes to one clone affect all other clones. This is feature makes it possible for a single outline to contain multiple views of a project. For example, when fixing a bug, I clone all nodes related to the bug and gather them in a new part of the outline, called a task node. This task node effectively becomes a view of the project that focuses exclusively on the bug. Any changes I make to code are propagated to all other clones.
Earlier I mentioned that a well designed Leo outline acts like self-updating tables of contents and self-updating indices. Tables of contents you get for free: an entire outline is the table of contents. Clones create self-updating indices. For example, each task node acts like the index entry for that particular task.
Last summer I added @file directives to Leo; if you haven't used Leo since then you might want to give it another look.
The difference between @root and @file trees is that files derived from @file trees are the primary documents (redundant information is also stored in.leo files). This means that if you change something in the derived (source) file, those changes automatically will appear when you next reload the outline. This makes it much much easier to integrate Leo into already existing workflows.
I would love it if all IDE's had outlining even remotely as powerful as Leo. Alas, none do, that I know of.
1. Leo allows the user to reorganize outlines freely by adding, deleting and moving nodes. IDE's dont.
2. Leo opens an outline as it was when the user last used it, restoring the selected node, the top visible node, and the expansion state of all nodes.
3. Leo supports cloned nodes, a crucial feature in project management.
I am the creator of Leo. As I said on another thread, Leo does not, in fact, enforce any particular viewpoint about comments. In fact, Leo makes organization primary, not either code or documentation.
Indeed, Leo often eliminates the need for comments, and certainly "roadmap" comments typically used in traditional literate programming. I discuss the roles of comments and literate programming here
I am the creator of Leo. Leo shows that the "stream of consciousness" style typically associated with literate programming can be replaced with a more effective organization, one that is more like a reference book.
So you could say that Leo turns literate programmers into reference librarians;-)
IMO, this topic has been explored fully in the book, Code Complete, by Steve McConnell, Microsoft Press, Chapter 19, especially pages the dialog between "pro" and "con" on page 457 and following. To summarize, some balance and perspective is needed;-)
However, as the creator of Leo, I would like to say that Leo does not, in fact, make documentation primary; it makes organization primary. In a sense, both code and documentation have secondary roles. So your view of the proper role of documentation really doesn't affect how you might use Leo.
I discuss the roles of Leo and documentation and literate programming in detail here
Slashdot Mirror
Edward
Leo does indeed support javadoc.
Edward K. Ream
Edward K. Ream
Leo really isn't all that much about either literate programming or documentation; it's about structure and clarity. I explain what Leo is in my posting, "The creator's view of Leo."
Edward K. Ream
A lot of people seem to feel qualified to comment about Leo after just reading the original slashdot article. Most have no clue about what Leo is or isn't. I've spent seven years working on Leo. I'm getting pretty annoyed about people commenting about Leo without even taking seven minutes to play with it.
Leo really isn't all that much about either literate programming or documentation. I explain what Leo is in my posting, "The creator's view of Leo."
Edward K. Ream
Please read my posting, "The creator's view of Leo."
Edward K. Ream
Please read my posting, "The creator's view of Leo." The short answer: Leo makes structure primary, rather than either code or docs.
Edward K. Ream
Please read my posting, "The creator's view of Leo."
Edward K. Ream
The pros and cons of documentation, inline or not, are not really relevant to what Leo is about. Please read my posting, "The creator's view of Leo". - Edward K. Ream
I would like to distinguish between the techniques of literate programming and the practice of literate programming (LP) as it has always been done before Leo (traditional LP). The key technique of LP is what might be called "functional pseudocode." For example, here is a fragment of code that can be written in Leo:
The line: << do something complicated >> is a section reference. It works pretty much like a macro call. In particular, the code in the defintion of << do something complicated >> has access to the done and result variables. This is almost the entire content of noweb, one form of literate programming. It turns out that this technique can be extremely useful, as simple as it seems. Leo creates one or more "derived" files from an outline automatically when the outline is written, and Leo can update the outline from changes made to derived files when Leo reads the outline.In contrast to the technique of literate programming, the practice of traditional LP has focused on the central role of comments, and lots of them. Here is where Leo radically parts company with the LP tradition.
One's view of the proper role of documentation in a project hardly matters to Leo. You are free to use comments as you always did, though you will probably find that LP as implemented in Leo helps you out in unexpected ways. I discuss at length and in great detail the relationship between traditional LP, comments and Leo here. In short, discussions about the role of comments in programming (literate or not) do not get to the heart of Leo.
In fact, Leo often reduces the need for comments. Indeed, it is good style to organize Leo outlines like a reference book. Well-designed Leo outlines act both like self-updating tables of contents and self-updating indices. This is in marked contrast to the "stream-of-consciousness" or "narrative" style typically employed in traditional literate programming.
In my view, the essence of Leo is this: Leo makes outline organization the most important part of a program or a project. Both code and documentation could be considered secondary. At every moment, the overall big picture of a function, class, module, file or project is always at hand. Moreover, Leo makes outlines structure a part of the computer language. For example, I often define a Python class as follows:
The @others directive acts as a reference to all the text in all the outline nodes which are descendents of the node containing this class declaration. Such nodes are copied to the output (derived) file in the order in which they appear in the outline. The reference << declarations of myClass >> ensures that those declarations precede the methods. There are several other ways that outline structure is important in Leo; I won't discuss them here.
Leo fully exploits the organizational power of outlines. A single outline typically organizes an entire project. Outlines can handle large amounts of data with ease. Moreover, it is possible to clone any part of an outline so that changes to one clone affect all other clones. This is feature makes it possible for a single outline to contain multiple views of a project. For example, when fixing a bug, I clone all nodes related to the bug and gather them in a new part of the outline, called a task node. This task node effectively becomes a view of the project that focuses exclusively on the bug. Any changes I make to code are propagated to all other clones.
Earlier I mentioned that a well designed Leo outline acts like self-updating tables of contents and self-updating indices. Tables of contents you get for free: an entire outline is the table of contents. Clones create self-updating indices. For example, each task node acts like the index entry for that particular task.
- Edward K. Ream
The difference between @root and @file trees is that files derived from @file trees are the primary documents (redundant information is also stored in .leo files). This means that if you change something in the derived (source) file, those changes automatically will appear when you next reload the outline. This makes it much much easier to integrate Leo into already existing workflows.
I would love it if all IDE's had outlining even remotely as powerful as Leo. Alas, none do, that I know of.
1. Leo allows the user to reorganize outlines freely by adding, deleting and moving nodes. IDE's dont.
2. Leo opens an outline as it was when the user last used it, restoring the selected node, the top visible node, and the expansion state of all nodes.
3. Leo supports cloned nodes, a crucial feature in project management.
- Edward K. Ream
Indeed, Leo often eliminates the need for comments, and certainly "roadmap" comments typically used in traditional literate programming. I discuss the roles of comments and literate programming here
- Edward K. Ream
So you could say that Leo turns literate programmers into reference librarians ;-)
-Edward K. Ream
However, as the creator of Leo, I would like to say that Leo does not, in fact, make documentation primary; it makes organization primary. In a sense, both code and documentation have secondary roles. So your view of the proper role of documentation really doesn't affect how you might use Leo.
I discuss the roles of Leo and documentation and literate programming in detail here
- Edward K. Ream