W3C home > Mailing lists > Public > public-webplatform@w3.org > December 2013

Little by little

From: Max Polk <maxpolk@gmail.com>
Date: Thu, 12 Dec 2013 13:24:28 -0500
Message-ID: <CADPfvJvPp55DcSZXXcKdSYLJHouRW83KqzF8_06vrAU7-kKx2g@mail.gmail.com>
To: Webplatform List <public-webplatform@w3.org>
I'd like to start surrounding JS imported page content, little by
little, in templates.

It appears a complex scheme exists to auto-generate the Syntax section, such as:
    http://docs.webplatform.org/wiki/apis/audio-video/AudioTrack/enabled

Nobody typed this in:
    var result = AudioTrack.enabled;
    AudioTrack.enabled = value;

Instead, various page properties were set. Go to the Tools | Browse
properties, and see things like:
    API name
    Example object name
    JavaScript data type
    Property applies to
    Return value name

This may not be the right approach.  The JS import pages aren't just
showing a property and return type, but a connected sequence of one or
more lines of code, followed by a matching parameter section.  Notice
how "arrayObj" and "size" and "element0" and "element1", etc
correspond between the code and the parameter section beneath:

 arrayObj = new Array()
 arrayObj = new Array([ size ])
 arrayObj = new Array([ element0 [, element1 [, ...[, elementN ]]]])

==Parameters==
; 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.

So just copying the concept from the /apis/ pages may not be the right
approach.  If so, designing page properties, page templates, semantic
forms, and other related things feel like a herculean task.  Designing
is a "top-down" approach.

I'm thinking of working from the bottom up.  Instead of completing a
full architectural design, I have actual pages to import, and maybe
the *best thing* I can do for now is to surround all content in the
right templates.  This would finish the work of JS page import, and it
would be in the state: "semantic form ready," and be fully compatible
with whatever top-down design occurs later.

Can I get a group consensus on me doing bottom-up work to fully
templatize the JS imported pages as my first task?

If we agree, I can simple wrap content in templates and the import is DONE.

To start, I can get *just* the top section of each page templatized.
Here is sample top-section templatized:

+=+=+=+= PAGE

http://docs.webplatform.org/test/javascript/Array

+=+=+=+= BEFORE

Provides support for creation of arrays of any data type.

 arrayObj = new Array() arrayObj = new Array([ size ]) arrayObj = new
Array([ element0 [, element1 [, ...[, elementN ]]]])

==Parameters==
; 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

{{Page_Title}}
{{Flags}}
{{Summary_Section|Provides support for creation of arrays of any data type.}}

{{JSPrototype|
 arrayObj = new Array()
 arrayObj = new Array([ size ])
 arrayObj = new Array([ element0 [, element1 [, ...[, elementN ]]]])
}}

{{JSParameter
| Name=arrayObj
| Required=true
| Description=The variable name to which the '''Array''' object is assigned.
}}

{{JSParameter
| Name=size
| Required=false
| Description=The size of the array. As arrays are zero-based, created
elements will have indexes from zero to size -1.
}}

{{JSParameter
| Name=element0,...,elementN
| Required=false
| Description=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.
}}

Have a look at the parameters above and see if this is good enough as
a bottom-up approach to fit into a master design that will come later.
Received on Thursday, 12 December 2013 18:25:00 UTC

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