W3C home > Mailing lists > Public > public-webplatform@w3.org > January 2014

Re: JS page templates and topics (analysis)

From: Doug Schepers <schepers@w3.org>
Date: Tue, 07 Jan 2014 02:48:54 -0500
Message-ID: <52CBB166.9040102@w3.org>
To: Max Polk <maxpolk@gmail.com>
CC: Eliezer Bernart <eliezer.bernart@gmail.com>, Julee Burdekin <jburdeki@adobe.com>, Webplatform List <public-webplatform@w3.org>
Hi, folks–

Sorry for the tardy response. I've been pondering this a bit. Here are 
some thoughts:

I agree that "Prototype" is too loaded a term there, but "Examples" is 
also loaded in the WPD context. I think that "Syntax" would be a good 
name for that section, and has analogs on other page types. What do you 
think?

Regardless of this issue, I think the templates and imports are good 
enough as-is to move to the main wiki. I'd like to get other opinions, 
and make the decision during Friday's meeting. If Max and Eliezer can 
attend then, that would be even better.

(FWIW, I don't think anything we do here will be irrevocable; we can 
take a little chance that we've made a mistake, and correct it later if 
we have. Making progress and getting closure is more important than 
perfection!)

Regards-
-Doug


On 12/30/13 10:35 AM, Max Polk wrote:
> The parameter is ephemeral information.  What matters is the example
> code.  For one example, there are zero, one, two, three, or whatever
> parameters used with random names (arrayObj, size, element0, elementN,
> etc):
>
> Example:
>      arrayObj = new Array([ element0 [, element1 [, ...[, elementN ]]]])
> Parameter for above example:
>      arrayObj (with description)
> Parameter for above example:
>      size (with description)
> Parameter for above example:
>      element0 ... elementN (with description)
>
> To create a template for the above, it has to emphasize that it is an
> example (a code form, an archetype, whatever you like), and zero or
> more tag-along parameters following in its trail.  Would you prefer a
> template named "Archetype" (meaning "a very typical example of a
> certain person or thing")?  Then there is one "Format" parameter with
> the typical way to use it, and zero or more parameter pairs named
> Parm1Name & Parm1Desc, Parm2Name & Parm2Desc, etc?
>
> If so, it would look something like:
>
> {{Archetype
> | Format=arrayObj = new Array([ element0 [, element1 [, ...[, elementN ]]]])
> | Parm1Name=arrayObj
> | Parm1Desc=Required. The variable name to which the '''Array'''
> object is assigned.
> | Parm2Name=size
> | Parm2Desc=Optional. The size of the array. As arrays are zero-based,
> created elements will have indexes from zero to size -1.
> | Parm3Name=element0,...,elementN
> | Parm3Desc=Optional. The elements to place in the array. This creates
> an array with n + 1 elements, and a '''length''' of n + 1. Using this
> syntax, you must supply more than one element.
> }}
>
> I know a variable number of parameters in a template is difficult but
> we could use the: (pseudocode) "if Parm1Name render it along with
> Parm1Desc; if Parm2Name render it along with Parm2Desc; etc" inside
> the template for variable parameter expansion.
>
> Are we getting closer to where we want to be?
>
>
> On Fri, Dec 27, 2013 at 1:06 PM, Eliezer Bernart
> <eliezer.bernart@gmail.com> wrote:
>> I agree! Prototype is a little bit confusing.
>>
>> But I don't think that JS_Example will be a good name, since we have the
>> other examples...
>>
>> A good solution for me it will be merge JS_Prototype with JS_Parameter, but
>> keep the JS_Parameter name.
>>
>> {{JS Parameter Value
>> |Name=arrayObj
>> |Required=true
>> |Description=The variable name to which the '''Array''' object is assigned.
>> |Example=arrayObj = new Array()
>> }}
>>
>> I made some updated on the Templates, and the Form in the last days Max, I
>> opened a Task on http://project.webplatform.org/msdnjs/issues/msjs-5.
>>
>> If you don't mind in give a check to see if I'm in the way or if there is
>> something that I'm doing wrong. All my changes are being applied at
>> http://docs.webplatform.org/test/javascript/Array
>>
>> What do you think?
>>
>>
>>
>> Eliezer
>>
>> @eliezerbernart
>> eliezerb
>>
>>
>> On Fri, Dec 27, 2013 at 3:51 PM, Max Polk <maxpolk@gmail.com> wrote:
>>>
>>> On 12/25/2013 11:06 PM, Eliezer Bernart wrote:
>>>
>>> Prototype
>>> * A basic sample of different prototypes to the object.
>>>
>>>
>>> I have a change of heart.  It feels that we should not use the word
>>> "Prototype" to describe examples at the top.  While the word "prototype" in
>>> English means one thing, it has a very different meaning in JavaScript, and
>>> we will cause confusion and lots of questions doing so.  Let us use another
>>> word, perhaps Example.
>>>
>>> Also, I feel we should merge JS_Protype and JS_Parameter since they
>>> contextually are highly coupled  What would you think of this.
>>>
>>> BEFORE (simple mediawiki text):
>>>
>>> arrayObj = new Array()
>>> arrayObj = new Array([ size ])
>>> arrayObj = new Array([ element0 [, element1 [, ...[, elementN ]]]])
>>>
>>> arrayObj: Required. The variable name to which the '''Array''' object is
>>> assigned.
>>> size: Optional. The size of the array. As arrays are zero-based, created
>>> elements will have indexes from zero to size -1.
>>> element0,...,elementN: Optional. The elements to place in the array. This
>>> creates an array with n + 1 elements, and a '''length''' of n + 1. Using
>>> this syntax, you must supply more than one element.
>>>
>>> AFTER (three examples, each with their independent set of parameters):
>>>
>>> {{JS_Example
>>> | Example=arrayObj = new Array()
>>> | Parameter1=arrayObj: Required. The variable name to which the
>>> '''Array''' object is assigned.
>>> }}
>>>
>>> {{JS_Example
>>> | Example=arrayObj = new Array([ size ])
>>> | Parameter1=arrayObj: Required. The variable name to which the
>>> '''Array''' object is assigned.
>>> | Parameter2=size: Optional. The size of the array. As arrays are
>>> zero-based, created elements will have indexes from zero to size -1.
>>> }}
>>>
>>> {{JS_Example
>>> | Example=arrayObj = new Array([ element0 [, element1 [, ...[, elementN
>>> ]]]])
>>> | Parameter1=arrayObj: Required. The variable name to which the
>>> '''Array''' object is assigned.
>>> | Parameter2=size: Optional. The size of the array. As arrays are
>>> zero-based, created elements will have indexes from zero to size -1.
>>> | Parameter3=element0,...,elementN: Optional. The elements to place in the
>>> array. This creates an array with n + 1 elements, and a '''length''' of n +
>>> 1. Using this syntax, you must supply more than one element.
>>> }}
>>>
>>> Some duplication, but since it's highly coupled, it makes it easier to add
>>> examples as independent units.  Like?  Dislike?
>>
>>
>
Received on Tuesday, 7 January 2014 07:49:06 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:20:56 UTC