[with patch, needs work] tear out docstrings in the notebook into a new window

[mpatel]

As mentioned in  this message, it might be useful to tear/pop/pull/rip out/off/up at least some notebook introspection window(s) into a separate window(s) [1].

This ticket, which builds on #5653 (see comments 19ff), is currently a disaster test area for variations on this theme.

Related: #4714, #5644, #5447, #5653, #6307.

[1] Nevertheless, they're all fine docstrings.

[mpatel]

Needs accompanying introspect.js

[mpatel]

For now, this should be javascript_local/introspect.js

[mpatel]

I've attached a first take. Directions:

• Apply docstring.4.patch from #5653.

• Apply trac_6001_tearout_docstring_v1.patch .

• Save introspect_v1.js to javascript_local/introspect.js, that is,

  SAGE_ROOT/local/notebook/javascript/introspect.js
  

• Remove .lock and .html files from the doc cache. The default location is DOT_SAGE/sage_notebook/doc/

[mpatel]

Notes:

• Ultimately, the open tab vs. open window decision comes down to a user's browser settings. The author can't force this either way, it seems.
• Opera 9 Linux: Works when "new window" links are set to open tabs or to open windows.
• Firefox 3 Linux: Works when set to open windows, but not necessarily when set to open tabs. The latter depends on whether introspect.open() opens a sized window. Please experiment with the  window.open() lines in introspect.js and let me know. Even with  FireBug's help, I don't know what's wrong.
• The new window and its children are generated dynamically, somewhat in keeping with the transient nature of Sage's introspection divs. Accordingly, commands like "view source" and "refresh page" may not work as expected.
• The font-sizing stuff is just an experiment.
• I have no strong opinions on cosmetic issues, including default font sizes, layouts, etc. Actually, I'd rather not make these decisions, so please make suggestions. Later, we can move CSS directives to css.py.
• Modulo ordering, the 'sagedoc' window should be a fixed point with respect to local tear outs.
• The unordered list of docstrings should be sortable, thanks to  jQuery UI. To see this, I temporarily disable Firefox's  Grab and Drag extension via ALT+SHIFT+D. Perhaps there's a workaround.
• The code in introspect.js is a mix of jQuery and DOM methods. This may not be optimal.
• Evidently, JavaScript is no Python, as  this video demonstrates.
• For now, introspect.close() won't work for "SHIFT-ENTER" docstrings, because the notebook treats them differently from "TAB" docstrings. See #5644.
• See #4714 about making jsMath inclusions and tweaks more manageable.

[mpatel]

Opera 9 Linux snapshot

[mpatel]

Firefox 3 Linux snapshot of "torn out" docstrings

[mpatel]

Unexciting inaction shots:

This ticket could really use your help.

By the way, to get rounded [docstring] borders in Firefox 3, put something like

div.docstring {
    -moz-border-radius: 0.5em;
    -webkit-border-radius: 0.5em;
}

in DOT_SAGE/notebook.css . I haven't tested this in Safari.

[jhpalmieri]

On a Mac, works well with Firefox but not with Safari. With Safari, clicking the tear-out button opens up a new blank window and leaves the docstring in the original window.

With Firefox, looks great, and I like font-resizing and toggling.

[mpatel]

Attempted support for WebKit? browsers. Replaces v1.

[mpatel]

I've tested the new, possibly improved `introspect.js` on Fedora 9 Linux in Firefox 3.0.10, Opera 9.64, and a Qt 4.5.0 WebKit-based "browser" demo.

I'm not sure about how well the latter, which I found in /usr/lib64/qt4/demos/browser, approximates Safari. It returns

"Mozilla/5.0 (X11; U; Linux; en-US) AppleWebKit/527+ (KHTML, like Gecko, Safari/419.3)  demobrowser/0.1"

when I enter navigator.userAgent in the JavaScript console (check the "Tools" menu or right-click on any element, then click on "Inspect"). To get "tab" introspection working, I just added 'sl':keyboard_saf near the end of keyboards.py. Perhaps this is related to ticket #4046.

Anyway, it seems all the browsers have their own way of doing just about everything, and no major UI library handles pop-ups seamlessly across browsers. We may not (cannot?) get identical behavior on all major browsers.

Some possible tests, besides the obvious:

• Check whether multiple tear-outs from a worksheet go to a common window.
• Ditto, from multiple worksheets.
• Ditto, after reloading a worksheet(s).
• Ditto, after navigating to another domain (e.g., google.com) in a tear-out window(s) (see  same origin policy).
• Check the behavior when tear-outs go to an unsized window and the browser is set to open tabs vs. set to open windows.
• Ditto for sized windows.

For the latter, see the window.open() lines in introspect.js. In Firefox, I still get a blank tab when I force new windows to open in tabs and use unsized pop-ups. I have got this to work with a somewhat different approach, but I haven't yet reconciled it with what's in v2.

Drag-and-drop sometimes behaves oddly in Firefox, adding copious spurious placeholders to the list. I've noticed this after I navigate to a different domain in a tear-out window, forcing the script to open a new window. I think this is a jQuery [UI] bug, since it goes away when I substitute the latest versions. This and other quirks may be a good reason to upgrade both. Worst case: Disable some tear-out features for certain browsers.

Some ideas, though my patience with browser "programming" has all but vanished:

• Do something server-side instead or in addition.
• Add a top-level toolbar to the tear-out window, e.g., to toggle, close, resize all docstrings.
• Add a simple "cell" input that calls window.opener.evaluate_cell_inspection().
• Cookies, preferably chocolate.

Some ideas related to #5653:

• Collect anonymous statistics on docstring access: compute correlations, do Bayesian predictions, rank the greatest (and worst) docstring writers of all time.
• Generate a large graph of all docstrings and their cross-links. Drive the graph theorists wild. Actually, I think it's rather sparse at the moment. Not an  expander?
• Upgrade Sphinx and test the Qt help builder, though it may  need work. Try running Qt's assistant (assistant-qt4 on Fedora 9) for a taste.
• Add "PDF" to the toolbar, with maybe a rude surprise for PDF plug-in users.
• One-click copy-pasting of examples for the truly lazy.

[mpatel]

Goes with layout_v3.html.

[mpatel]

Goes with introspect_v3.js.

[mpatel]

Version 3 is up. Please see the code and comments for details. In particular, see the new layout.html for alternative Unicode "icons." Perhaps we can use jsMath, here, too. Anyway, suggestions are welcome. Note: I thought up/down arrows for font-sizing might be [more] confusing. Perhaps someday we can add left/right arrows for browsing consecutive docstrings in a module.

I've tested this, though not exhaustively, in Opera 9, Firefox 3, and the Qt 4.5 demo browser on Linux, as well as IE 8, Opera 9, Firefox 3, Safari 3, and Chrome 2 on Windows XP.

[mpatel]

Goes with layout_v4.html.

[mpatel]

Goes with introspect_v4.js.

[mpatel]

Version 4 is available. New features: multiple columns, height limits. Tested on Linux in Opera 9 and Firefox 3. Note: Drag-and-drop in the latter is still problematic, but a jQuery/UI upgrade will fix this. To do:

• Add a function to "balance" or "equalize" columns, either by the number of docstrings or, perhaps, instantaneous total height.
• Query sage-devel for volunteers to design nice icons?
• Test on Mac OS X, though I can't do this myself.
• Re-test on Windows.

By the way, running

html('<script>introspect.test1(10)</script>')

in a cell should open 10 docstrings selected not quite at random. Alternatively, evaluate introspect.test1(10) in  Firebug's console. See the code for details.

[mpatel]

See  sage-devel for thoughts about something almost completely different. See  also.

[timdumol]

I think this has been fixed by one of the recent patches (~January). Close?

[mpatel]

This ticket was originally about [optionally] tearing out documentation into an independent browser tab/window, where one could browse and collect docstrings and source code separately from a worksheet(s). I'd like to keep the ticket open, for now, to pursue a more general Sage documentation browser, about which I've speculated  here.  Miller Columns still seem promising, and we could adapt an existing JavaScript widget. I'll need to do another survey to get an update list of candidates.