Subject: Feedback on the document structure

From: Steve Hole <[email-masked]>
Date: Wed, 3 Feb 1999 11:43:31 -0700

Hi Tim.   I have some suggestions for changes to the text of the document 
that I think would make it clearer.     I have to admit to not having done
a cover to cover read for some time.    Sorry about that.

Anyway here are some suggestions.   I was trying hard to think about what 
someone being introduced to the language would see rather than read it 
with knowledge of the components in place.     I hope this is helpful Tim.

Cheers.
---

pg7 p3

   Implementations of the language are expected to take place at time of
   final delivery, when the message is moved to the user-accessible
   mailbox.  In systems where the MTA does final delivery, such as and
                                                                ^^^^^^
   traditional UNIX mail, it is reasonable to sort when the MTA deposits
   mail into the user's mailbox.

sec 2.1. Form of the Language

I found that I wanted to use the term "tokens" to describe the language
(from a true language parser's point of view :-).  You could substitute
"objects" "sequences" "doodads" -- whatever -- for tokens. Anyway,
something like:

   The language consists of a set of commands.   Each command consists
   of a set of UTF-8 string tokens delimited by whitespace.   The first
   token is the command string followed by 0 or more arguments.
   Arguments can be either literal data, tests, or blocks of commands.

   The language is represented in UTF-8, as specified in [UTF-8]

sec 2.2 - 2.9 Reordering

I would suggest the following reordering:

 2.2. Evaluation
 2.3. Commands
 2.3.1.  Positional Arguments
 2.3.2.  Optional Arguments
    Move discussion on tagged arguments here.

    I think you need to mention that some commands will accept other
    commands as arguments.   Specifically the control commands accept
    test commands and action commands as arguments.

    Incidentally, it is still not clear to me why we need the tagged
    argument support at all.  The stated contract for the optional
    argument should be enough.  Beyond saying that this is "optional"
    I'm not sure what information it conveys.  If optional arguments
    always follow positional arguments, then even syntactically it
    offers nothing useful.
    
 2.4. Whitespace
 2.5. Comments
 2.6. Literals

Changes to "Literal data"

First paragraph is a bit awkward -- specifically with the definition of
execution.   I tend to think in terms of "evaluation" for interpretters.
Now that we have a "token" concept introduced, perhaps something more like

   Literal data tokens are evaluated "as is" by a SIEVE interpretter and
   consist of two types; numbers and strings.  Many commands accept
   literal data arguments.

I'm not in love with this myself so feel free to hack it up.   In
general when discussing syntactic elements I would always use the term
evaluation (because that is what the interpretter does) and use
execution when discussing the result of evaluation.   Subtle difference
but important.

sec 2.6.  Tagged Arguments

The discussion on tagged arguments needs to be moved up or introduced
sooner.  They imply a structure that needs to be more clearly stated as
a "meta" structure for arguments.   In particular there is reference to
"positional arguments" vs. "tagged arguments", but there is no
definition for positional arguments.    I recommend that fold this into
the general introduction to commands and arguments.

sec 2.9.  Evaluation

This section needs to be expanded to include:
 - evaluation ordering
 - control issues
 - command argument processing
 - evaluation results ie.  what happens when you evaluate a control 
command vs. a test command vs. an action.

Note that this provides a nice seguay into the next topic (in the reodered
list) on commands.

sec 3. Control Structures

Change the title "Control Structures" to "Control Commands"

sec 4. Actions

Change the title "Actions" to "Action Commands".

sec 5. Tests

Change the title "Tests" to "Test Commands"

---  
Steve Hole                           
Execmail Inc.
Mailto:[email-masked] 
Phone: 780-424-4922

---

From: Tim Showalter <[email-masked]>
Date: 11 Feb 1999 13:10:36 -0500

> From: Steve Hole <[email-masked]>
> Date: Wed, 3 Feb 1999 11:43:31 -0700

So by and large, I'm happy to take your comments on Sieve.  I'm working
on the document now, and trying to figure out exactly what you want, and 
in a couple cases I'm confused.

>    Arguments can be either literal data, tests, or blocks of commands.

I think I took that paragraph.  There are probably other changes to be
made here to clean up stuff all over the document, but Larry's grammar
is the biggest one and is in my working copy.

>  2.3.2.  Optional Arguments

(Please excuse the editing of your message.)

I don't like this order better than the one in the document, but we can
probably improve on the one in the document.

My intent was to define things from the bottom up, not the top down.  I
see you want the exact opposite.

>     test commands and action commands as arguments.

ok.

>     argument should be enough.

So this is probably just not clear.  First, all optional arguments are
tagged arguments that can be left out (otherwise, it's hard to tell
which arguments are which).  Otherwise, if a command has two optional
arguments, and you want to leave one out, you can't tell which one was
omitted.

The further reason for tagged argument support is so that we can
introduce new modifiers to commands--if someone adds a new match keyword 
for header, I don't want to have to add it directly to the grammar.

I will move the discussion of arguments to one place and try and clean
it up.  Obviously it's gotten a little confused.

>     Beyond saying that this is "optional"

I can see the need for change, but I don't agree with this order.  I'll
try and nail down the tokenizer so that this stuff is a little more
ordered, 

>    consist of two types; numbers and strings.  Many commands accept

I rewrote your literal data paragraph as follows:

| Literal data means data that is not executed, merely evaluated "as
| is", to be used as arguments to commands.  Literal data is limited to
| numbers and strings.

I hope that's ok.

> the general introduction to commands and arguments.

Ok.  I'll try to produce something more verbose for positional
arguments; I think I know what you want.

> command vs. a test command vs. an action.

I am not sure what you want.  Could you be more specific?  I thought all 
of this stuff was mostly obvious, I guess.

> Change the title "Tests" to "Test Commands"

ok.

-- 
Tim Showalter <[email-masked]>

---

From: Tim Showalter <[email-masked]>
Date: 11 Feb 1999 13:43:05 -0500

> Date: 11 Feb 1999 13:10:36 -0500
> From: Tim Showalter <[email-masked]>

> arguments, and you want to leave one out, you can't tell which one was

Actually, there's an inconsistancy in the draft.  The MATCH-KEYWORD
argument is described both as being a tagged argument and an optional
argument; this is certainly my fault.

The MATCH-KEYWORD defaults to being ":is".

I have two questions:
	Should it be optional?
	Should it default to ":is"?

I don't care if it's optional, but if it is, should it default to
":contains" instead?

I've reworked the sections on arguments, put them all in one place,
better described positional arguments, and described optional arguments
as tagged arguments that can be left out.  The text from the nroff
source is this.

.xx "2.6. Arguments"
In order to specify how they function, most commands take arguments.  There
are three types of arguments: positional, tagged, and optional.

.xx "2.6.1. Positional Arguments"
Positional arguments are given to a command which discerns their meaning based 
on their order.  When a command takes positional arguments, all positional
arguments must be supplied, and must be in the order prescribed.

.xx "2.6.2. Tagged Arguments"
This document provides for tagged arguments in the style of CommonLISP.  These 
are also similar to flags given to commands in most command-line systems.

A tagged argument is an an argument for a command that begins with ":", and
consists of a tag naming the argument, such as ":contains".  This argument
means that zero or more of the next tokens have some particular meaning,
depending on the argument.  These next tokens may be numbers or strings, but
are never blocks.

So tagged arguments are similar to positional arguments, except that instead
of the meaning being derived from the command, it is derived from the tag.

Tagged arguments must appear before positional arguments, but they may appear
in any order.  For convienence, this is not expressed in the syntax
definitions with commands, but they still may be reordered arbitrarily
provided they appear before positional arguments.  Tagged arguments may be
mixed with optional arguments.

To keep the language simple, tagged arguments should not take tagged arguments 
as arguments.

.xx "2.6.3. Optional Arguments"
Optional arguments are exactly like tagged arguments except that they may be
left out, in which case a default value is used.  Because optional arguments
tend to result in shorter scripts, they have been used far more than tagged
arguments.

One particularly noteworthy case is the ":comparator" argument, which allows
the user to specify which ACAP comparator will be used to compare two strings,
since different languages may impose different orderings on UTF-8 [UTF-8]
characters.

---

From: Steve Hole <[email-masked]>
Date: Tue, 16 Feb 1999 21:23:33 -0700

> as tagged arguments that can be left out.  The text from the nroff

This is much better.    The analogy to the Unix command line stuff did the
trick for me.     The discussion on the benefit of the ":" tagging helps 
alot when thinking about a flexible parser that can accept extensions.

Cheers.

---  
Steve Hole                           
Execmail Inc.

---

From: Steve Hole <[email-masked]>
Date: Tue, 16 Feb 1999 21:36:33 -0700

> of this stuff was mostly obvious, I guess.

Oh sure, ask a hard question.   

I really can't remember what this was about specifically.   I think that I
was looking for an explicit discussion on the ordering of evaluation of the
language.   Ie. each line is evaluated in order, top to bottom.   Is the 
entire script parsed before evaluation or can you parse a line at a time 
(I know the answer).

Please excuse the obvious onset of senility.   Bottom line is that if I 
can't remember then it can't have been that important.    I'l see if it 
comes back to me when I reread the new text.

Cheers.
---  
Steve Hole                           
Execmail Inc.