Re: Missing Essentials

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.


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


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


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

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

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

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

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

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

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

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



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

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