RE: [office-formula] Punctuation issues

["Dennis E. Hamilton" <dennis.hamilton@acm.org>]

Concerning the naming of parameters, I think that italic type is preferable.
I also recommend lower-case to avoid confusion with type names which are
already capitalized.  I recommend against italic type for type names (I
misunderstood this practice in a previous note), because they are already
capitalized as proper nouns.

With regard to the descriptive phrases, the only convention that I have seen
is that if they are phrases but not sentences, they should not begin with an
initial capital (unless a common noun is at the beginning) and no
punctuation is used at the end of the phrase.  

[EXCEPTION: If the portions of parameter description are meant to be read as
phrases in sentences, then appropriate punctuation is required and the
tip-off is usually the presence of verbs.

E.g.,

    Parameters

       startDate     ordinal-day representation of 
                     of the earliest calendar date 
                     included in the interval

       endDate       ordinal-day representation of 
                     the first calendar date after 
                     the interval

in comparison with,

    In the parameter list,

       startDate     is the ordinal-day representation 
                     of the earliest calendar date 
                     included in the interval;

       endDate       is the ordinal-day representation 
                     of the first calendar date after 
                     the interval.

So long as we are using the example of dates and ParamDate, we should also
be able to learn somewhere:

    When a Number for an ordinal day is provided directly, 
    its interpretation as a calendar date is relative to the 
    setting for NULL-DATE that applies in the context of the
    function reference.

    [NOTE 1: When startDate is for the same day as endDate, 
     the interval has 0 days duration.  When endDate is in
     the next day past the day of startDate, the interval
     has duration of 1 day. {This could probably be put
     somewhere in the treatment of days and calendars too.}

     NOTE 2: It is possible for startDate and endDate to
     be for the same day even though startDate != endDate,
     i.e., when FLOOR(startDate) = FLOOR(endDate).]

   ]

-----Original Message-----
From: Eike Rathke [mailto:erack@sun.com] 
Sent: Monday, December 28, 2009 09:18
To: office-formula@lists.oasis-open.org
Subject: Re: [office-formula] Punctuation issues

Hi Patrick,

On Wednesday, 2009-12-23 10:05:58 -0500, Patrick Durusau wrote:

> Just a placeholder but something we need to remember to clean up:
>
> 1) With no particular pattern, listings of parameters end with a period  
> or no period. Suggest period and consistent use.

I agree.

> 2) At PPMT, Nper becomes nPer.

In the current draft OpenDocument-formula-20091222.odt it is nPer in
Syntax, Constraints and Semantics. However, at the PMT function it is
Nper. I'd suggest to name both NPer instead, or better NPeriods.

> I didn't bother to create a separate  
> listing for it. So whatever we call these tokens we need to proof for  
> single form.

I'd prefer having _all_ parameters start with a capital letter, unless
they are Greek symbols like alpha or beta or some such, which sometimes
also would make them easier distinguishable in the Semantics text. Care
would have to be taken that mathematical formulas would need to be
adapted as well.

  Eike

-- 
Automatic string conversions considered dangerous. They are the GOTO
statements
of spreadsheets.  --Robert Weir on the OpenDocument formula subcommittee's
list.