Opened 8 years ago

Closed 2 years ago

#6001 closed enhancement (fixed)

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

Reported by: mpatel Owned by: boothby
Priority: minor Milestone: sage-duplicate/invalid/wontfix
Component: notebook Keywords:
Cc: jhpalmieri Merged in:
Authors: Reviewers: Karl-Dieter Crisman
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description (last modified by 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.

Attachments (9)

trac_6001_tearout_docstring_v1.patch (1.8 KB) - added by mpatel 8 years ago.
Needs accompanying introspect.js
introspect_v1.js (6.4 KB) - added by mpatel 8 years ago.
For now, this should be javascript_local/introspect.js
tearout_opera.png (35.6 KB) - added by mpatel 8 years ago.
Opera 9 Linux snapshot
tornout_firefox.png (89.4 KB) - added by mpatel 8 years ago.
Firefox 3 Linux snapshot of "torn out" docstrings
introspect_v2.js (10.9 KB) - added by mpatel 8 years ago.
Attempted support for WebKit? browsers. Replaces v1.
introspect_v3.js (13.6 KB) - added by mpatel 8 years ago.
Goes with layout_v3.html.
layout_v3.html (2.3 KB) - added by mpatel 8 years ago.
Goes with introspect_v3.js.
introspect_v4.js (19.5 KB) - added by mpatel 8 years ago.
Goes with layout_v4.html.
layout_v4.html (2.4 KB) - added by mpatel 8 years ago.
Goes with introspect_v4.js.

Download all attachments as: .zip

Change History (23)

Changed 8 years ago by mpatel

Needs accompanying introspect.js

Changed 8 years ago by mpatel

For now, this should be javascript_local/introspect.js

comment:1 Changed 8 years ago by mpatel

I've attached a first take. Directions:

  • Save introspect_v1.js to javascript_local/introspect.js, that is,
  • Remove .lock and .html files from the doc cache. The default location is DOT_SAGE/sage_notebook/doc/

comment:2 Changed 8 years ago by mpatel


  • 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 opens a sized window. Please experiment with the 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
  • 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.

Changed 8 years ago by mpatel

Opera 9 Linux snapshot

Changed 8 years ago by mpatel

Firefox 3 Linux snapshot of "torn out" docstrings

comment:3 Changed 8 years ago by mpatel

Unexciting inaction shots:

Opera 9 Linux snapshot Firefox 3 Linux snapshot of "torn out" docstrings

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.

comment:4 Changed 8 years ago by jhpalmieri

  • Cc jhpalmieri added

comment:5 Changed 8 years ago by 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.

Changed 8 years ago by mpatel

Attempted support for WebKit? browsers. Replaces v1.

comment:6 Changed 8 years ago by 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 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., 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 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.

Changed 8 years ago by mpatel

Goes with layout_v3.html.

Changed 8 years ago by mpatel

Goes with introspect_v3.js.

comment:7 Changed 8 years ago by 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.

Changed 8 years ago by mpatel

Goes with layout_v4.html.

Changed 8 years ago by mpatel

Goes with introspect_v4.js.

comment:8 Changed 8 years ago by 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


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.

comment:9 Changed 8 years ago by mpatel

  • Description modified (diff)

comment:10 Changed 7 years ago by mpatel

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

comment:11 Changed 7 years ago by timdumol

  • Report Upstream set to N/A
  • Work issues set to Close/mark as fixed?

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

comment:12 Changed 7 years ago by mpatel

  • Work issues Close/mark as fixed? deleted

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.

comment:13 Changed 2 years ago by kcrisman

  • Milestone set to sage-duplicate/invalid/wontfix
  • Reviewers set to Karl-Dieter Crisman
  • Status changed from needs_work to positive_review

The original thing mentioned has long since been done, as pointed out, and the other piece is just far too vague to merit a specific ticket. After five years, probably time to close.

comment:14 Changed 2 years ago by vbraun

  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.