Re: JS page templates and topics (analysis)

Hello,

Today I merged the "JS Parameter" and the "JS Prototype" templates for the
JS Object form.

As we discussed on the last conversations, and following the Doug's and Max
suggestions, here are the new templates:


{{JS Syntax
|Format=
|Values=
}}

{{JS Syntax Parameter
|Name=
|Required=
|Description=
}}


I used composed templates to allow multiple values for Parameter, not sure
if these are the best names for that. So, let me know if something should
be changed. And here are the links to see the changes:

Example page:
http://docs.webplatform.org/test/javascript/Array
http://docs.webplatform.org/t/index.php?title=javascript/Array&action=formedit

Form page:
http://docs.webplatform.org/test/Form:JS_Object

Templates:
http://docs.webplatform.org/test/Template:JS_Syntax
http://docs.webplatform.org/test/Template:JS_Syntax_Parameter
http://docs.webplatform.org/test/Template:Syntax_Form_Section

It'll be great to have some feedback about the changes. Thanks!




Eliezer

@eliezerbernart
eliezerb


On Tue, Jan 7, 2014 at 5:48 AM, Doug Schepers <schepers@w3.org> wrote:

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