[Date Index] [Thread Index] [Author Index]

Comments on online documentation

• To: mathgroup at smc.vnet.net
• Subject: [mg90821] Comments on online documentation
• From: AES <siegman at stanford.edu>
• Date: Fri, 25 Jul 2008 06:16:11 -0400 (EDT)
• Organization: Stanford University

The following are neither questions nor gripes/criticisms, just 
observations on some of the idiosyncrasies, inconsistencies, and 
generally odd behavior one encounters in dealing with the online 
documentation:

1)  Open an ordinary notebook: up/down arrows are immediately 
functional; Find command is immediately functional; Page Up/Down keys 
are immediately functional; you can start typing immediately -- no mouse 
clicking needed for any of these.

2)  Open a typical documentation window, for example by positioning the 
cursor just after a M function name, symbol name, or an ordinary word 
and hitting Help key or typing cmd-shift-F:

--One or another kind of M-appearing window opens, e.g. a M Function 
Definition (FD), a M Symbol (MS), or a M Search Results (MSR).

--Up/down arrows are NOT immediately functional -- you can't immediate 
start scrolling down through the window using the arrow key (would be 
nice if you could)

--For some windows, Find command is immediately functional, but for 
others (notably SR windows), it's NOT.

--On windows where it's not immediately functional, you can (sometimes, 
anyway) click or double-click in the window, and the Find command, and 
also up/down arrow keys will start functioning (but it sometimes seems 
as if the conditions under which one or the other function will work are 
not the same).

--This is especially true for MSR (search result) windows: depends on 
how you click.  Find will start working if you select a single text 
word, for example -- but will only find text words, not the same string 
in highlighted symbol names.  Sometimes repeated clicks in the Find 
dialog box (or cmd-G, or Return) will wrap around through all the text 
on the page; sometimes not.

--M Search Result pages (MSRs) are often 100s to 1000s of items long, 
extending over literally 100s of screens or pages -- which means they 
are essentially worthless and useless for any practical purpose, unless 
you can _search_ down into them for more specific information -- right?  
But, so far as I can tell, you can't -- nor (so far I've found, anyway) 
can you rapidly page down through subsequent pages with the arrow or 
Page Up/Down keys. 

--Try going back and forth between a notebook and an M documentation 
window, by clicking in the window, or clicking on something in the 
window, or by clicking on the menu bar, and so on, then doing things in 
the doc window.  Behavior can be sufficiently complex and variable that 
I won't try to describe it. 

3)  Various other oddities:  Apply the "position insertion point after a 
word in a notebook and activate Help" technique to various terms, e.g.:

--"Grid" takes you to a MSR page; but GridBox takes you to an MS page.

--Hmmm -- maybe that means more generic terms like Grid (which is a 
component of longer names as well) will take you to an MSR but specific 
terms like GridBox take you directly to the relevant MS page.  

--But no: GridBox takes you to its MS age, but GridLine takes you to an 
MSR page.  And Plot takes you to an MS -- but "plot" takes you to an MSR.

--and so on.

---------

All in all:  Dealing with M's online document is fun; frustrating; and 
much less helpful than it ought to be.

• Follow-Ups:
  • Re: Comments on online documentation
    • From: Andrzej Kozlowski <akoz@mimuw.edu.pl>