GNOME Bugzilla – Bug 337584
ideas for new TOC layout
Last modified: 2006-07-22 14:56:58 UTC
This is a tracker bug for new TOC layout ideas.
Created attachment 62892 [details] [review] proof of concept this is a rough proof of concept for what I was talking about here: http://mail.gnome.org/archives/gnome-doc-devel-list/2006-April/msg00003.html Right now it breaks for man and info pages (try clicking on them on the left side and you'll see what I mean). The problem is that we create three separate in-memory documents (omf toc, man toc, info toc) and then convert them three different times using toc2html.xsl in yelp-toc-pager.c. If we were able to create a single in-memory document with all tocs (omf, man and info) and process that just _once_ with toc2html.xsl, I believe that would fix the problem. Unfortunately the recursive xslt seems to slow down yelp startup a little, but that can possibly be addressed...
Created attachment 63016 [details] [review] Another proof of concept Based on Brents work, this patch does several things: 1. Only displays categories if there are something in them. 2. Adds a yelp icon behind the categories list (faintly) and (a very faint) grey background behind the doc list. 3. Adds a "Help Topics" link at the top of the categories list. 4. Adds a message to the top of each section. I've only added (somewhat stupid) descriptions to the Desktop category (and subcategories), but the idea is there. 5. Added the words "Subsections:" and "Documents:" to the main area before the respective bits. 6. Promotes the Desktop guide et. al. to the front page. Just because. I haven't managed to fix the man page stuff. And yes, the recursive xslt is taking its toll: Before: ~2.5s to display the TOC from a warm cache After: ~3.7s
Created attachment 63044 [details] [review] updated patch based on DonS that fixes man problem, and adds info pages. Ok, this is not complete, but I wanted to submit it so that others can play with it if they want. This patch is based off of DonS' and fixes a number of problems. 1) the man page problem where the left sidebar was changing.. 2) turns back on the info pages 3) trims titles for non-default languages from info page toc There are still other problems to address: 1) toc2html.xsl is slow now 2) Man and Info should be hidden under top level category "Command Line Help" All in all, I think this is a big improvement to the TOC as far as usability is concerned.
Here are some profile runs on toc generation: This is the stylesheet which supports infinite level expansion on the left sidebar. smitten@home:/extra/cvs/gnome2/yelptest$ /usr/bin/time -- xsltproc --profile toc2html2.xsl toctest.xml > profile.txt number match name mode Calls Tot 100us Avg 0 toc leftbar.mode 100 203198 2031 1 toc body.mode 32 33803 1056 2 toc 32 4269 133 3 / 1 5 5 Total 165 241275 2.50user 0.09system 0:02.67elapsed 96%CPU (0avgtext+0avgdata 0maxresident)k 0inputs+0outputs (0major+10706minor)pagefaults 0swaps This next profiling run is for a stylesheet which only shows the top level categories on the left. smitten@home:/extra/cvs/gnome2/yelptest$ /usr/bin/time -- xsltproc --profile toc2html2.xsl toctest.xml > profile.txt number match name mode Calls Tot 100us Avg 0 toc leftbar.mode 32 47217 1475 1 toc body.mode 32 33684 1052 2 toc 32 4497 140 3 / 1 4 4 Total 97 85402 0.97user 0.05system 0:01.15elapsed 89%CPU (0avgtext+0avgdata 0maxresident)k 0inputs+0outputs (0major+6472minor)pagefaults 0swaps smitten@home:/extra/cvs/gnome2/yelptest$ Summary: infinite levels on left: 2.41 seconds top levels on left: 0.85 seconds I can't seem to optimize the XSLT anymore... so I'd like to hear what people think about the tradeoffs between startup time and a greater level of usability. Or maybe there are other ideas to speed things up?
Created attachment 63280 [details] [review] hackish patch to do on-demand loading of TOC pages. This is a very hackish patch that solves the speed issue by doing on demand page loads for TOC pages instead of generating them all at startup. With this patch, yelp startup is again almost instantaneous. (~1 sec) Thoughts?
Lazy loading works great here. I am getting a critical warning on startup though (which doesn't seem to affect the loading itself): (yelp:30604): Yelp-CRITICAL **: toc_pager_resolve_frag: assertion `priv->toc_doc != NULL' failed One point though (on further thought), as the background colour of the right panel (the very light grey) is hard-coded in. This doesn't play nice with certain themes (high-contrast inverse for example). This needs removing or one of the many colours we already pass in should be used. Also, the categories on the left should probably be rethought if this is put in as the Desktop category (at least) looks a little silly and comming up with descriptions for each category is a little difficult for now.
Yeah I get the same thing. Not sure how to fix it.
Created attachment 67664 [details] [review] fix some bitrot with the patch so it applies to HEAD going to look into the error at startup in the next few days. Here's some output using the [awesome] new debug infrastructure smitten@home:/extra/cvs/gnome2/yelp-head5$ YELP_DEBUG="all" YELP_DEBUG_FILTER="yelp-window" /opt/gnome2/bin/yelp yelp-window.c:911: yelp_window_load: entering yelp-window.c:912: uri = "x-yelp-toc:" yelp-window.c:1000: window_do_load: entering frag_id=(null) (yelp:4936): Yelp-CRITICAL **: toc_pager_resolve_frag: assertion `priv->toc_doc != NULL' failed yelp-window.c:1956: pager_start_cb: entering yelp-window.c:1957: page_id="(null)" yelp-window.c:2039: pager_finish_cb: entering yelp-window.c:911: yelp_window_load: entering yelp-window.c:912: uri = "x-yelp-toc:" yelp-window.c:1000: window_do_load: entering frag_id=(null) yelp-window.c:1956: pager_start_cb: entering yelp-window.c:1957: page_id="index" frag_id=(null) found the frag_id=index yelp-window.c:1773: window_handle_page: entering yelp-window.c:1774: page->page_id = "index" yelp-window.c:1775: page->title = "Help Topics" yelp-window.c:1776: page->contents = 5544 bytes yelp-window.c:1854: uri = file:///opt/gnome2/share/yelp/toc.xml yelp-window.c:3165: idle_write: entering yelp-window.c:3171: context->buffer = 5544 bytes yelp-window.c:3172: context->cur = 0 yelp-window.c:3173: context->length = 5544
Created attachment 67666 [details] [review] fix pager_finish_cb to only throw the error if the fix pager_finish_cb to only throw the error if the current frag_id can not be resolved. This fixes the error at startup... Is this too big of a hack to apply?
Not sure if it's too hacky or not, I'll let Shaun decide (?) A couple of other points though: 1. The grey background is still hardcoded. As noted above, this breaks accessibility. Not too difficult to fix (I don't think). I'll have a look soon. 2. The TOC categories and descriptions may need changed slightly. Personally I'd still love to see this done this cycle, the new TOC actually looks quite good and browsing it feels much cleaner. However, the approach taken may be a little too hacky. If it doesn't cause any new problems, and its only temporary (until the shiny new API appears), it may not be too bad. If the plan is to commit, then first get it committed, then worry about point 2 above, I think.
Created attachment 68626 [details] [review] latest patch This is the latest patch which fixes both of the previous issues mentioned by Don. I would like to apply this to HEAD before monday's release (2.15.4), but I would like feedback before I do so. The only thing that might be an issue is that Man pages and Info pages are back at a top level category. Since the categories expand now, I think this is better. Otherwise there can be 4 levels (Command Line Help -> Man Pages -> Applications -> X11 Applications is just one example)
Created attachment 68633 [details] screenshot of the new layout
Created attachment 68693 [details] [review] blah, another patch. last patch before I commit tomorrow, unless I get some objections.
Please move the categories bar to the right next to the scrollbar and the mouse pointer (you'll notice this bugzilla, planet.gnome.org and probably many others put the navigation bar there for this reason)
(In reply to comment #14) > Please move the categories bar to the right next to the scrollbar and the mouse > pointer > > (you'll notice this bugzilla, planet.gnome.org and probably many others put the > navigation bar there for this reason) > For every other doc type in yelp, the sections go on the left (as is sane and reasonable). I'm not sure moving them to the right for the TOC makes sense - it would break expectations. For bugzilla, p.g.o etc., the info provided in the right side is ancilliary info, that you can (probably) survive without. For Yelp, the info in the left pane is required to navigate yelp. Different porposes.
that just means you need to move the other sections to the right too ;) You'll notice the login is on the right in bugzilla, so it's hardly ancilliary info. Putting navigation columns next to the scrollbar is usability 101 - many apps like for example ms office have been doing it for a long time (the reason is to avoid loom-like back-and-forth between navigation and scrollbar for users of wheel-lacking mice)
For all of the documents, the sections on the left are in a seperate pane, so there are no scrolling problems. For these pages, I think they're fundamentally different than the web pages you mention. This bug report, for instance, has over a dozen screen heights of information in my browser. That's all real content, and navigational stuff is in a right sidebar. These pages aren't full of content. They have links to documents and links to more categories of documents. It's not so much a content area with a sidebar as it is a two-column layout. For reasonable window sizes (and we keep the definition of reasonable pretty small for Yelp), there shouldn't be more than about two screens of information.
Patch has been committed. Closing. (For the Mallard TOC, we should open a new bug when it becomes relevant) 2006-07-10 Brent Smith <gnome@nextreality.net> * data/info.xml.in: * data/man.xml.in: * data/scrollkeeper.xml: * data/toc.xml.in: - Restructure the table of contents to make most documentation accessible via a single click (except for man pages and info pages) - Put descriptions for each section at the top in the right side above the document listing - Rename the top level category to 'Desktop' and include the User guide, System Administration Guide, and Accessibility Guide in this section * src/yelp-pager.c: (yelp_pager_get_page_from_id): * src/yelp-pager.h: * src/yelp-toc-pager.c: (toc_pager_resolve_frag), (toc_process_pending), (process_mandir_pending), (process_info_pending), (process_read_menu), (process_cleanup): * src/yelp-window.c: (window_do_load_pager), (pager_finish_cb): Load each table of contents page on demand instead of creating all pages at once. * stylesheets/toc2html.xsl: Maintain a list of categories on the left hand side in the table of contents, that expands subcategories for the currently selected category