Re: yet another todo editing system

[Joe Corneli <jcorneli@mail.ma.utexas.edu>]

> > A feature for browsing programs certainly ought to be part of Emacs.

> One way to think about this feature would be to instantiate a function
> prototype (a b c) -- as in, (insert &rest ARGS) -- as something like
> this: ((a "link a") (b "link b") (c "link c")) -- where "link a"
> points to

>> You have lost me here.  You were talking about browsing, and now
>> you're talking about instantiating something.

>> I can't understand what this is all about.

Hoof.  Ok.  Sorry about the vagueness.  I had a head cold and a
terribly slow internet connection when I was writing last night.
Now both are considerably better.

Let me try to clarify what I was talking about.

A central point is that both Todo and Lisp are oriented towards lists.
The fact that my program works exclusively with lists as opposed to
plain text is the constraint inherent to the "structured editing
environment" I mentioned offhandedly a while ago.

When a person writes Lisp code, they are working within a similarly
constrained environment (assuming they want their code to compile).
Lisp code is made up of lists of strings.

Here is an example of a Lisp function I just wrote, set up in a
traditional style and indented by Emacs.

(defun grape ()
  (interactive)
  (switch-to-buffer "*grep*")
  (beginning-of-buffer)
  (next-line +2)
  (let ((lines (simple-count-lines-page))
        (line (simple-what-line)))
    (while (not (equal line lines))
      (switch-to-buffer "*grep*")
      (next-line +1)
      (setq line (+ 1 line))
      (compile-goto-error)
      (find-file-other-frame (buffer-name))
      (other-frame -1))))

And here is a version of the same function as it might be represented by
Todo.  As is typical with Todo, we find the text spread across several
files.  Recall that the syntax of the lines that make up Todo files is
"<char> text <<filename>>", which means "<user-specified markup code>
link description <<file-we-link-to>>".

grape:
< > defun <<defun>>
< > grape
< > nil <<nil>>
< > interactive <<interactive>>
< > switch-to-buffer <<switch-to-buffer.local>>
< > beginning-of-buffer <<beginning-of-buffer>>
< > next-line +2 <<next-line+2>>
< > let <<let.local>>

let.local:
< > let <<let>>
< > VARLIST <<let_VARLIST.local>>
< > BODY <<let_BODY.local>>

let_VARLIST.local:
< > lines <<simple-count-lines-page>>
< > line <<simple-what-line>>

simple-count-lines-page:
-- OMITTED --

simple-what-line:
-- OMITTED --

let_BODY.local:
< > while <<while.local>>

while.local:
< > while <<while>>
< > TEST <<while_TEST.local>>
< > BODY <<while_BODY.local>>

while_TEST.local:
< > not <<not.local>>

not.local:
< > equal <<equal>>
< > line <<let_VARLIST.local>>
< > lines <<let_VARLIST.local>>

while_BODY.local:
< > switch-to-buffer <<switch-to-buffer>>
< > next-line +1 <<next-line+1>>
< > setq <<setq.local>>
< > compile-goto-error <<compile-goto-error>>
< > find-file-other-frame <<find-file-other-frame.local>>
< > other-frame -1 <<other-frame-1>>

setq.local:
< > setq <<setq>>
< > line <<latest_definition_of_line>>
< > + <<+>>
< > 1 
< > line <<latest_definition_of_line>>

latest_definition_of_line:
< > initial value <<let_VARLIST.local>>
< > inside while loop <<setq.local>>

find-file-other-frame.local:
< > find-file-other-frame <<find-file-other-frame>>
< > buffer-name <<buffer-name>>

other-frame-1:
< > other-frame <<other-frame>>
< > -1

switch-to-buffer.local:
< > switch-to-buffer <<switch-to-buffer>>
< > "*grep*"

next-line+1:
< > next-line <<next-line>>
< > 1

next-line+2:
< > next-line <<next-line>>
< > 2

In the above, every file with the suffix "local" is (a representation
of) what I was calling an "instantiation" in my earlier email.  For
instance, the "let" I use in the definition of the function "grape" is
an instantiation of the function "let" defined in Emacs.  This is
slightly different from the "defun" I use.  The "defun" used in the
definiton of "grape" is exactly the same as any other "defun" you might
find in standard Lisp code.  So I don't point to a "local instantiation"
of defun, but rather to the Todo file that describes defun.

I've taken a liberty in the file let_VARLIST.local by making the 
link descriptions the same as the value of the variable that is being
set.  A more consistent version of let_VARLIST.local would be:

let_VARLIST.local:
< > first variable <<let_VARLIST.first_variable.local>>
< > second variable <<let_VARLIST.second_variable.local>>

let_VARLIST.first_variable.local
< > lines
< > simple-count-lines-page <<simple-count-lines-page>>

let_VARLIST.second_variable.local
< > line
< > simple-what-line <<simple-what-line>>

Another potentially confusing point is that I only have one
"switch-to-buffer.local".  In a more complicated function, there might
be several different "instantiations" of switch-to-buffer.  (We might
have (switch-to-buffer "*scratch*") as well as (switch-to-buffer
"*grep*"), for example.)  The file names used by Todo would have to
be adjusted to reflect this multiplicity.