ietf-mta-filters
[Top] [All Lists]

Re: Feedback on the document structure

1999-02-11 11:06:40
From: Steve Hole <steve(_at_)execmail(_dot_)com>
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.

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.

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.

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
 2.4. Whitespace
 2.5. Comments
 2.6. Literals

(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.

 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.

ok.

    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.

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'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

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, 

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 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.

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.

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

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.

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 "Control Structures" to "Control Commands"
Change the title "Actions" to "Action Commands".
Change the title "Tests" to "Test Commands"

ok.

-- 
Tim Showalter <tjs+(_at_)andrew(_dot_)cmu(_dot_)edu>


<Prev in Thread] Current Thread [Next in Thread>