editing wiki docs on jquery.com

[David Serduke]

I was doing some editing today on the jquery.com docs wiki and I
noticed something called 'results' but I'm not sure where that
information is shown. So does that need to be updated as well? If so
it makes it quite a bit more difficult to add meaningful and useful
examples. For example, what is the result of a .click(function()
{alert("hi");}) ?

As I write this I see that click() doesn't have a results but the
selector I was changing does. Can I just delete it?

Thanks,
David

[John Resig]

Yeah, that should be fine. The |results= stuff is rather deprecated
now, anyway - as it's preferred to have live demos instead. This is
done by specifying a |code= and a |html= (and optional a |css=) - and
no |results=. This will generate a working demo for users to interact
with (which is highly preferrable).

Let me know if you have any questions.

--John

[David Serduke]

On Oct 4, 2:22 pm, "John Resig" <jere...@gmail.com> wrote:
> Let me know if you have any questions.

Just a few more I think.

First, have any sections of jQuery Core been assigned yet for this
Great Documentation Drive? I don't want to mess up anyone else's
work.

And second, if I think the current documentation is incorrect but I'm
not sure, is this the right place to ask? For example, it currently
says for jQuery() "This function accepts a string containing a CSS or
basic XPath selector which is then used to match a set of elements"
but I thought I read the XPath stuff was removed although I'm not
positive. Is this forum the best place to ask for verification?

Last, is there a process for reviewing docs when they are finished or
should I just announce it here? (I wish I could claim to be perfect
and make no errors but...)

David

[David Serduke]

Ack, one more Q.

I was testing and redid

http://docs.jquery.com/Selectors/id#id

without |results= and at the same time I tried to clean up the
formatting of the View Source tab. To do that I had to put and remove
white space in some odd places (edit to see). For example, I needed
an extra CR after the |css=<nowiki>, put 2 spaces before the |css </
nowiki>, and remove a CR from before the |html= </nowiki>. I don't
mind doing that but it occurred to me if the code generation for the
View Source changes it will look quite odd and have to be redone
again. So my question is do you want me to add/remove/change
whitespace to make the View Source nicely formatted or do you want to
change the code generator? I'm ok either way but only one should be
done.

David

[David Serduke]

Comment this time.

It looks like the generated source in the wiki is running in
quirksmode. I noticed because some of the animations are behaving
oddly.

David

[David Serduke]

I went ahead and did the Selector section of the wiki today. Mostly
just altering the demos.

http://docs.jquery.com/Selectors

Hopefully no one else was working on that. Any comments on what I did
are welcome. I tried to mix it up a bit. Hopefully I didn't make
anything too complicated.

Just let me know if you want more help in documenting.

David

[David Serduke]

Well I added the doctype to fix the animation problem. Hopefully that
is ok. It did seem to add a border around the iframe in IE7 although
I think it looks fine. Looking at the syntax of the wiki templates I
decided not to mess with the code generation. I'll just work with the
whitespace formatting as necessary.

As for other bits, it looks like the demos in FF (they do in IE)
aren't working in the examples tab so I stopped trying to put them in
for now. Also, just fyi, the tabs under the generated iframes in IE
are way off. It looks the the positions are calculated pre iframe
creation so are off by the 125 pixel height. I don't know how high of
a priority it is but if there is some way to reposition the tabs right
after these lines it might help.

var iframe = document.createElement("iframe");
iframe.src = "/index-blank.html";
iframe.width = "100%";
iframe.height = $(this).prev().attr("rel") || "125";
iframe.style.border = "none";
$(this).prev().append(iframe);
// fix tab positions in ie

I tried to figure it out as far as I could. I don't quite understand
why they are off actually since their position is static but it's
tough arguing with IE. Something like

if ($.browser.msie) $("li").hide().show();

might work. That's quite some fancy footwork being done in the wiki
scripts changing from one format to another on the fly. :)

Anyway, just some thoughts.

David

[Jörn Zaefferer]

On Oct 5, 12:08 am, David Serduke <davidserd...@gmail.com> wrote:
> On Oct 4, 2:22 pm, "John Resig" <jere...@gmail.com> wrote:
>
> > Let me know if you have any questions.
>
> Just a few more I think.
>
> First, have any sections of jQuery Core been assigned yet for this
> Great Documentation Drive? I don't want to mess up anyone else's
> work.

Dunno about that. But as long as just edit and save changes, its
rather unlikely that you'll get in conflict with anyone else.

> And second, if I think the current documentation is incorrect but I'm
> not sure, is this the right place to ask? For example, it currently
> says for jQuery() "This function accepts a string containing a CSS or
> basic XPath selector which is then used to match a set of elements"
> but I thought I read the XPath stuff was removed although I'm not
> positive. Is this forum the best place to ask for verification?

Due to activity you can get faster responses on the general discussion
list. Otherwise this is the right place.
In this case: You are right, XPath support was removed in 1.2 and is
available only via the XPath selector plugin.

> Last, is there a process for reviewing docs when they are finished or
> should I just announce it here? (I wish I could claim to be perfect
> and make no errors but...)

Well, in the end, every reader reviews your work and is free to
correct any errors he spots. It may take a bit longer then an actual
review, but should suffice for now. If you'd like to get specific
feedback on a certain page, just ask here.

[Jörn Zaefferer]

Thanks for your work David! I can't really help with those wiki
issues, I hope John finds some time to take another look at them.

On your Selectors work: I like how I don't even have to look at the
source because the element's text explains it all. It would be perfect
to have this in all examples.
- ancestor descendant fails here, I can't "see" the form, while the
inputs are obvious
- same in parent > child
- etc. pp.

Descriptions referring to selector argument can be rather irritating.
For example, I think this one:
- Matches all next elements specified by next that are next to
elements specified by prev.
Is easier to grasp when argument names are quoted:
- Matches all next elements specified by "next" that are next to
elements specified by "prev".
I've changed that for hierachy selectors.

:nth-child(index) maybe incomplete, though I'm not exactly sure how
much jQuery supports there - it should also accept "even" or "odd" as
arguments.

Again, great work!

[David Serduke]

Thanks for the comments. :)

On Oct 12, 3:13 am, Jörn Zaefferer <joern.zaeffe...@googlemail.com>
wrote:

> On your Selectors work: I like how I don't even have to look at the
> source because the element's text explains it all. It would be perfect
> to have this in all examples.
> - ancestor descendant fails here, I can't "see" the form, while the
> inputs are obvious
> - same in parent > child
> - etc. pp.

I rewrote the first two heirarchy examples so hopefully they are more
clear.

> Descriptions referring to selector argument can be rather irritating.

As for the descriptions, I have to admit I focused more on the demos
and sometimes even forgot to read the descriptions. Most of the
descriptions seemed pretty good already but I'll try to look more
closely when I have time to do more demos.

> :nth-child(index) maybe incomplete, though I'm not exactly sure how
> much jQuery supports there - it should also accept "even" or "odd" as
> arguments.

Wow. I hadn't realized all it could do. But I'm not sure I
understand how it interprets the formulas it takes. Like I'm not sure
why 3n+1 would return [ Second, Fifth, Eighth... ] and 3n+2 returns
[ First, Fourth, Seventh... ] and n returns all children but n+1 just
returns the First. This might be best left undocumented (by me at
least) unless someone can explain it. I might try even and odd
although there is also :even and :odd (which are of course the
opposite since they are zero index based so that might be confusing as
well).

> Again, great work!

Thanks. :)

David

[Jörn Zaefferer]

> Wow. I hadn't realized all it could do. But I'm not sure I
> understand how it interprets the formulas it takes. Like I'm not sure
> why 3n+1 would return [ Second, Fifth, Eighth... ] and 3n+2 returns
> [ First, Fourth, Seventh... ] and n returns all children but n+1 just
> returns the First. This might be best left undocumented (by me at
> least) unless someone can explain it. I might try even and odd
> although there is also :even and :odd (which are of course the
> opposite since they are zero index based so that might be confusing as
> well).

Yet nth-child(even) works different then :even if you are dealing with
multiple "parents". The table zebra striping example is the best
usecase for nth-child: "table tr:even" would select all trs within
tables, then only those even. "table tr:nth-child(even)" selects even
trs for each table, in other words, starts "counting" again for each
table.

For a start it may suffice to reference/copy a few lines from the CSS
spec and just highlight the difference to :even/:odd.

Jörn

[David Serduke]

I put together another demo you can check out if you get the chance.
It's in the Examples tab.

http://docs.jquery.com/Selectors/nthChild

David