Re: Missing Essentials

Thank you very much for the extensive response. Since a few days have
passed, I started to assume it was not the right place for such discussions.
See my responses to your responses inline.

Additional essentials and discussions (forgive the occasional duplication
of your suggestions, some of this list was written before your reply) -

9. An option to mark an example code as a snippet.
A check box should be added to the example template for marking an example
as a snippet. It should add something like (Code snippet) (maybe formatted
in a special way or something) to the beginning as well as the end of such
example.
For example (used to be in
http://docs.webplatform.org/wiki/css/cssom/currentStyle, ignore the syntax
errors) -

<script>
function checkColor(oObj)
{
  if (oObj.currentStyle.backgroundColor == 'brown')
 {
        oObj.style.backgroundColor = 'white';
 }
  else
 :
}
</script>*</head>*
:
<p style="background-color: 'brown'"
    onclick="checkColor(this)">Click me</p>


10. The ability to encourage basic (and not so basic) best practices in
examples - HTML, CSS, JavaScript separation.
Currently, the examples generally contain a mix of languages. In the
example above, you can see HTML code and JavaScript code, mixed, as an
inline script, as an inline event handler and as an inline element style.
These are not best practices.
Any example that combines more than one language could and should be easily
separated, with fields for each language that include a file name field (or
might just be unified to always be "example.js", "example.css" and so on,
with a counter suffix if needed more than one external file of that
language) and a raw code field (and related to 10, a snippet check box?).

11. Automatic escaping of example code.
It is time consuming and tedious to always use &lt; (and similar) instead
of normal code. The form should just escape the code automatically on
submit.
Also, I believe there is a bug here. Escaping with &lt; and such are added
in preview mode as raw code, that is executed and and that affects the
preview page (CSS and stuff). Other than it being confusing, I believe it
might be a little dangerous.

12. As an alternative solution to 6 - add another field to the CSS property
template for the CSSOM name of property (float is cssFloat, font-weight is
fontWeight) and make it act as a property when it applies to the
CSSStyleDeclaration (well, actually CSS2Properties or something, this needs
to be clarified a bit...).

13. Indicate a method/property is non standard, deprecated and so on.
Add a few check boxes to the API method/property/object (and more...)
templates to indicate that it is non standard, deprecated, proprietary or
obsolete (supported only in Netscape 2, for example, or only on HTML 3) -
each of them should get a check box.
This information should show up on the property/method tables of the
"Applies to..." object. Ideally, anything marked as such would reside in a
separate section below everything that is standard/current, so users would
not be encouraged to use it.

14. SVG CSS properties should get a different template, or be separated
somehow and still have the same CSSOM counterparts like regular CSS.
Stuff like "stroke-linecap", for example.
Perhaps create a dummy SVGCSSStyleDeclaration that incorporates everything
that is SVG CSS only?
Once properties are converted to regular CSS (like pointer-events), just
change their template to CSS property.

15. Inherited methods should show up through the whole chain.
Element <http://docs.webplatform.org/wiki/dom/Element> subclasses
Node<http://docs.webplatform.org/wiki/dom/Node>,
which subclasses EventTarget<http://docs.webplatform.org/wiki/apis/EventTarget>
.
But addEventListener (applied to EventTarget) does not show up in the
Element article (it does show up in the Node article).

16. Constants on interfaces/constructors should be defined within an API
Object/constructor/interface templates.
dom/Node should include constants like Node.ATTRIBUTE_NODE and so on.
There is no point in maintaining lots of pages just for the purpose
including them as constant properties on their API Objects.
We should be able to add them within the interface/constructor
template/page itself.

☆*PhistucK*



On Thu, Oct 25, 2012 at 8:51 AM, Alex Komoroske <komoroske@google.com>wrote:

>
>
> On Sat, Oct 20, 2012 at 6:44 PM, PhistucK <phistuck@gmail.com> wrote:
>
>> I am currently going through the various articles, cleaning up content
>> and creating missing articles and I find a few essential things that are
>> missing in or from the templates (or missing templates).
>>
>
> Awesome!  I'm so glad to see you participating in WPD. :-)
>

I am so glad and excited to see Web Platform Docs actually happening, it
was necessary since forever. Let us hope the entire Web community will use
it like I wish it would.


>  This is a partial list. I will keep on posting updates when I find new
>> essentials.
>>
>> I will be glad to help set these up, of course. If this is feasible, any
>> guidance would be very much appreciated.
>>
>
> You should check out
> http://docs.webplatform.org/wiki/WPD:Implementation_Patterns to get a
> very high-level sense of how we've implemented stuff. I'm looking forward
> to having more people know how to work within templates/ forms.
>

I will read it, thank you.


>
>> 1. A template for constructors, with the ability to set a constructor as
>> 'non constructible' (which essentially makes it an interface, rather than a
>> constructor, but it is still a type), for things like HTMLElement, Window
>> and other constructors that emit the "Illegal constructor" error message
>> when, for example, new Window() is entered.
>> Currently
>> http://docs.webplatform.org/wiki/apis/xhr/objects/XMLHttpRequest is
>> using a simple text to show the constructor syntax, but there should be a
>> unified template for constructors/interfaces.
>>
>
> I think this makes sense. Are you proposing a template that would be
> included within the content of  other page types?
>

I am sorry, I do not understand your question. However, I think the answer
is yes. :)


>
>> 2. The ability to specify multiple "Applies to..." values.
>> This is useful for the "name" property (and others, like "pathname" and
>> other URL decomposition properties that apply to several
>> objects/interfaces/classes as well), since it exists on certain HTML
>> elements (but not all) according to the specifications and you cannot
>> subclass them to an imaginary element (HTMLElementWithName ;)), because
>> that would just be... wrong(?).
>>
>
> This is something I've been meaning to do. It should just require a bit of
> ArrayMap usage in the templates.
>

In case this is explained in the link you mentioned above, I will check it
out and see if I can make progress here.


>> 3. More types in the return value and parameter types.
>> Basically, anything with the constructor template should be a type.
>> This arbitrary basic selection box just does not quite cut it.
>>
>
> I added a link in the form UI next to that section to describe how to add
> more types. Basically just add it to
> http://docs.webplatform.org/wiki/Property:Javascript_data_type .
>

Once we have a constructor/interface template in order, I think the list of
data types should draw from pages that include these templates. Do you know
if this is possible?


>
>> 4. A constructor template for DOM properties, I guess.
>> Example -
>> There is the XMLHttpRequest object -
>> http://docs.webplatform.org/wiki/apis/xhr/objects/XMLHttpRequest
>> And then there is the XMLHttpRequest Window property -
>> http://docs.webplatform.org/wiki/apis/xhr/properties/XMLHttpRequest
>> That type of the property should be XMLHttpRequest and it should be a
>> constructor.
>> The current example shows var xhr = window.XMLHttpRequest, which is not
>> how you would really use it.
>> Perhaps the property page should just be removed, I am not sure.
>>
>
> Perhaps we should add it as an option on the property, which will allow
> the syntax block example to automatically be generated with the right
> syntax.
>

That sounds like a good solution (in lieu of a real constructor/interface
template)..


>> 5. Not specifying a "Subclass of" value for dom/ articles, automatically
>> assumes dom/Element, which is incorrect.
>> A lof of a dom/ articles do not talk about Element subclasses.
>>
>
> Do you have any example of one that shouldn't use that?
>

dom/location (which implements Location, which is missing right now, if I
recall correctly), but I believe there are more, much more.
However, I guess this specific example should converge with apis/location
or something like that.
See http://docs.webplatform.org/wiki/dom, it has a lot of pages that should
not inherit from dom/Element.
- dom/FormData
- dom/CSSFontFaceRule
- dom/DOMTokenList
And more.


>
>
>>
>> 6. The CSSOM property template should automatically get its value(s) from
>> its CSS property counterpart.
>> If that does not happen, every value has to be updated twice - once for
>> the font-weight and once for fontWeight.
>> I doubt everyone (anyone?) will remember that.
>>
>
> Are you saying that that field on the CSS Property template should
> automatically be generated based on a transform of the name of the
> property? I agree we should, but I don't know what magic parser
> functions/processing we'd have to do to make that work in mediawiki markup.
>

I wish it could have been automatic, but there are always exceptions
(however, it could be automatic with exceptions, now that I think about it,
I guess, like the example names for API Objects/methods/properties that
have defaults (object, result)).
I am not familiar with the MediaWiki system in a sufficient way to know -
is it possible to include JavaScript code within the edit form?
If so, this would be the (easy) solution here.


>
>>
>> Additional discussions -
>> 7. I created the EventTarget API object -
>> http://docs.webplatform.org/wiki/apis/EventTarget
>> However, I am pretty sure I created in the wrong place and it might even
>> not supposed to even exist in the documentation, since it might be just an
>> implementation detail of some sort (there is no EventTarget under Window
>> when checking with Google Chrome).
>> I had to create it (or something along these lines), because a lot (or
>> more than one, anyway) of interfaces subclass it, like Node, Document,
>> Window.
>> Any suggestions?
>>
>
> This is an interesting case. I think it does make sense to have, but
> perhaps in the dom/ URL structure (as in, a sibling of Element).
>

I think I agree.
I will move it.


>
>> 8. Related to 1, 7 - should there be articles for the Document (not
>> document) and Window (not window) intefaces?
>> I guess there should be a dom/interfaces (maybe not only DOM ones,
>> though) sub topic.
>> HTMLElement, Document, Window and the rest of the interfaces would just
>> go into it.
>>
>
> Is there a reason to have a separate interface article when the interface
> is only implemented by one object?
>
>
For consistency and accuracy, yes. We should strive to be as accurate as
possible.
We might be able to simplify stuff for the common reader (hiding the
interfaces in the case you talk about).


>
> By the way, these are great, very in-depth questions that demonstrate a
> very deep understanding of some of the complex and arbitrary pieces in the
> site.
>

Well, I have worked on it for a few full days now. ;)


>
>>
>> ☆*PhistucK*
>>
>>
>