[Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation

[Georg Brandl]

Am 28.11.2010 01:43, schrieb Steven D'Aprano:
> Georg Brandl wrote:
>> Hi,
>> 
>> at <http://dpo.gbrandl.de/contents>, you can look at a version of the 3.2
>> docs that has the upcoming commenting feature.  JavaScript is mandatory.
>> I've switched on anonymous comments for testing, but usually at least
>> comments from anonymous users can be moderated.  Be sure to test the
>> "propose a change" feature too.  Login currently allows OpenID exclusively.
> 
> Testing as an anonymous user with Konqueror 3.5.9
> =================================================
> 
> I can show comments, and add them, but I can't hide them once shown.
> 
> Once I add a comment, the UI for adding a comment (text field and Add A 
> Comment button) disappears.

That is intended.  I don't think many users will want to leave multiple
comments at one time, and I put in that feature to actively discourage
Columbo-style commenting.  The field can always be brought back by
re-opening the comment popup.

> "Propose a change" doesn't work for me *at all* -- it just scrolls to 
> the top of the page.
>
> Likewise for the "sort by" links, the "markup" links and the Vote Up and 
> Vote Down buttons.
> 
> There are no "Reply" and "Proposal" controls visible.

That is all noted, looks like I'll have to test the UI more with Konqueror.

> 
> Testing with Epiphany ("Gnome Web Browser") 2.18.3
> ==================================================
> 
> The text field and Add A Comment button also disappear after adding a 
> comment. Hiding the comment block and re-showing it makes it return.
>
> The sort by and markup links seem to work. The threading model is 
> unintuitive and strange -- if I reply to a comment, the reply doesn't 
> show up anywhere near the comment I replied to.

That is a bug and needs to be fixed.

> I would suggest that proposals should be visible by default.

The problem is that they take a *lot* of space.  But it needs to be
more visible that there *is* a proposal.

> The algorithm used to highlight changes in proposals is 
> counter-intuitive. For example, I proposed a change to this text:
> 
>      factorial.  Raises :exc:`ValueError` if *x* is not integral
>      or is negative.
> 
> by inserting the word "interestingly" before "integral":
> 
>      factorial.  Raises :exc:`ValueError` if *x* is not
>      interestingly integral or is negative.
> 
> This was highlighted as:
> 
>      factorial.  Raises :exc:`ValueError` if *x* is not
>      inteRESTINGLY INTEgral or is negative.
> 
> instead of the more intuitive:
> 
>      factorial.  Raises :exc:`ValueError` if *x* is not
>      INTERESTINGLY integral or is negative.

That's difflib for you.  I don't really want to roll my own here.

> Performance really is poor :( There is a noticeable lag on even hiding 
> and showing the smallest thing.

A bit of lag is expected when loading comments, but inside the comment
popup everything should be smooth.  I know of problems with large pages,
but if it's slow even on the math page, it seems that that browser is
really behind in terms of JavaScript optimizations...

Thanks for testing,
Georg