Re: Missing Essentials

Okay, reviving this months-old thread. This has been one of the
longest-lived action items in my inbox for a couple of months now...

On Fri, Oct 26, 2012 at 6:20 AM, PhistucK <phistuck@gmail.com> wrote:

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

Agreed.

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

That would be nice. Do you have any suggestions for how to get it to work?


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

I agree that this is a problem. We've talked with Yaron about it (the
creator of semantic forms)--it's most likely a bug in the way Semantic
Forms works.


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

We have a structured field for this already:
http://docs.webplatform.org/wiki/Template:Standardization_Status . If this
were set correctly for every leaf reference article, theoretically we
should be able to write the queries for the Applies_to object to surface
this automatically.


>
> 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).
>

We specifically don't do this for performance reasons. The only way to
implement this in SMW (that I'm aware of) would be to write ~10 queries to
pull in all of the properties/methods of your superclasses--if they exist.
This would mean that every API_Object, whether or not it has many
superclass ancestors, would be very expensive to generate for every
API_Object page, and still it would only work up to a constant number of
ancestors up the chain.

The way it works today is that each API_Object can specify a specific
comma-delimited list of articles to pull in in the sublcass_of field. That
way you can be explicit about which methods and properties should be
included in the page, and we don't do more queries than are necessary.


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

Sounds reasonable. There has been more discussion on this since this e-mail
was sent; I forget, was the result of the discussion to have pages for
specific enums of constants?

>
> ☆*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*
>>>
>>>
>>
>