Re: Missing Essentials

I have sent this a few days ago, but I might have misled you into thinking
it was a blank message.
See my comments inline (I am mostly looking for feedback regarding the
Deprecated/Non standard flag implementation below).
☆*PhistucK*



On Fri, Oct 26, 2012 at 9:01 AM, Alex Komoroske <komoroske@google.com>wrote:

>
>
> On Fri, Oct 26, 2012 at 4: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.
>>
>
> Sorry about that--I'm in Tokyo this week for business and have been busy
> with things. I'm the one who did the most work to set up the current
> templates, so I think other folks weren't chiming in because they don't
> know the area as well.
>
>

No need to apologize! I am glad someone actually replied eventually and got
the discussion going. :)


> See my responses to your responses inline.
>>
>
> I've responded inline, but in general I think your ideas are spot on. *Do
> you want to file bugs on the bugzilla to track these?* That will make
> sure we don't forget these awesome ideas. Feel free to set me as the owner.
> In practice, we may want to split up the work on these if you're able to
> help.
>
>

Hehe, I knew it will come to that... I will try. ;)


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

 I will give it a shot, then.


>
>
>> 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?).
>>
>
> I think this is a good idea, and it should be *relatively *easy to
> accomplish by having an additional nested template type.
>

I will investigate further.


>
>> 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.
>>
>
> I reached out to the creator of Semantic Forms about this. I agree that
> the preview mode bug is confusing (at best).
>
> As for auto escaping of code, I'm not sure how we could best accomplish
> that directly in media wiki/semantic forms.
>

Once (if ever) we have this JavaScript feature in place, this should be a
piece of cake.


>
>> 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.
>>
>
> There's an ability to mark any reference article (including
> Methods/Properties) as being standard/obsolete/non-standard, etc.  Making
> it so that those would be pulled out in the summary tables on API Objects
> should be relatively easy. Another good thing t o
>

I gave it a shot. I created two test bed templates for this purpose -
http://docs.webplatform.org/wiki/Template:API_Listing_New
http://docs.webplatform.org/wiki/Template:Summary_Table_Body_New

A few questions -
1. How do you test template changes? I created new templates just for the
sake of experimentation, because I would not want to break all of the
template users while experimenting/making changes. Is there another way?
2. I added a #switch that searches for Non-Standard or Deprecated (I could
easily add more, if needed, like Obsolete, which I think should be added to
the Standardization_Status options) and adds a styled span (it would be
better if I used a class and added it to some global CSS). Does that seem
fine (the style could use some work, of course ;))?


>
>> 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).
>>
>
> This could get very expensive to do, because the code on each API Object
> page would have to run a separate query for each level up the chain, even
> if those levels don't exist.
>
> The work around that's currently implemented (and I think is better) is
> that each API_Object page accepts a comma-delimited list of pages in the
> Subclass_of field. If you provide more than one, it will print them all out
> on the page (although not collated together). This is not very clear in the
> current documentation of the templates.
>

It is only better because it is easier and less expensive. ;)
This workaround will not keep things up to date when some class suddenly
becomes a sub class due to some specification re-factoring of some kind
(granted, that does not happen a lot).

And I did not know it works. I have seen some instances of multiple values
there, but it always seemed to yield no heritage in the view. It does work
now, cool.

I guess I still do not quite understand the processing flow just yet. I
thought any "query" or anything "prgrammatic" is cached and so nothing is
expensive at run time, but only at save time.
If that does not happen, listing the methods on an object sounds pretty
expensive to me.


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

I will give it a shot. This is pending further discussion in the "Creating
API pages" thread.


>
>> ☆*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. :) t
>>
>>
>>>
>>>> 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.
>>
>
>
> http://www.mediawiki.org/wiki/Extension:Semantic_Forms/Semantic_Forms_and_templatesis where ArrayMap is documented. You can see it in action in
> http://docs.webplatform.org/wiki/Template:API_Object , among other pages.
>

I will look into it.


>
>>
>>>> 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?
>>
>
> Hmmm. The main documentation for semantic forms is:
> http://www.mediawiki.org/wiki/Extension:Semantic_Forms/Defining_forms .
> Based on that, I think the answer is no. The reason is that even if we were
> to use "values from category", the page titles would all be too long. What
> we'd want is the *last bit of the title *for every page in the group.
>

We seem to do it in other areas, for example, "Inherited from *(last bit)*",
using {{#titleparts:@@@@||-1}} - is it possible there, too?


>
>>
>>>
>>>> 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)..
>>
>>
I will look into it.


>>>> 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.
>>
>>
> Hmm, that must have been an error in the import. For now the best way to
> fix this (and this is not an ideal answer, I know) is to manually remove
> the erroneous values in the Subclass_of form field for each of those
> articles. :-/
>

Well, the issue I presented here was that when it is left empty, it still
used dom/Element. Perhaps it was a cache issue when I encountered it,
because it does not reproduce anymore. Solved! :)


>
>
>
>>
>>>
>>>>
>>>> 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.
>>
>
> Unfortunately, I don't believe it's possible to include javascript in the
> semantic forms. If there are a number of places where this would be useful
> (I think we've enumerated a few just in this e-mail), it might be useful to
> ask the creator of Semantic Forms if it's possible to do that.
>
> I just investigated a bit more and it's not obvious to me how to do the
> appropriate conversion in MediaWiki markup/parserfunctions.
>

Now that I read your response again, I did not quite mean what you wrote,
but that is another issue, indeed.
I meant that the CSSOM property (cssFloat, for example) should draw its
values from the CSS property (float). Meaning -
cssFloat should show these accepted values and it should draw them from its
CSS property counterpart automatically -
- none
- left
- right


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

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