MathGroup Archive 2009

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

Search the Archive

Re: Re: Any way to make help browser remember the last

  • To: mathgroup at smc.vnet.net
  • Subject: [mg98822] Re: [mg98761] Re: Any way to make help browser remember the last
  • From: danl at wolfram.com
  • Date: Mon, 20 Apr 2009 01:31:44 -0400 (EDT)
  • References: <gs1nro$7h5$1@smc.vnet.net> <gs47in$7m5$1@smc.vnet.net>

> In article <gs9ej8$mrj$1 at smc.vnet.net>,
>  Daniel Lichtblau <danl at wolfram.com> wrote:
>
>> AES wrote:
>> > [...]
>> > If the Help material (and other documentation) for Mathematica were
>> > written and displayed in another app and format (like, for example,
>> > Adobe PDF), as is the case with most other major applications, you
>> could
>> > jump back and forth between your active Mathematica windows and your
>> > currently active documentation window(s), leaving both of them
>> > absolutely stable and unchanged in between viewings, with a single
>> > keystroke, Cmd-Tab (on a Mac, anyway).
>> >
>> > Works like a charm; I do it all the time with other apps.  And,
>> > documentation in the form of a PDF file can be scanned, viewed,
>> > searched, enlarged, read, and generally used _immensely_ more
>> > effectively and easily in, say, Adobe Acrobat (or probably Reader,
>> > though I don't use that) than documentation in Mathematica's cramped
>> and
>> > awkward format.
>>
>> These other applications and their documentation display tools, how well
>> do they handle input and evaluation of mathematical content?
>
>       I appreciate that there can be some value in being able to
>       evaluate Mathematica examples or cells that are contained
>       within the Mathematica documentation pages, directly within
>       those pages.
>
>       I personally do not find that I make much use of this, however --
>       and when I do want or need to do so, I can always (and would
>       generally prefer to) copy the example (which is almost always a
>       brief single cell or example) into my own running copy of
>       Mathematica (which would be necessarily running anyway), where
>       I can modify or customize it to apply to the situation I want to
>       understand.

It has been pointed out that this is not a trivial undertaking if the
format is anything other than InputForm. And it involves extra work on the
part of the user. The point being that whatever method we use for
documentation, some people will need to do extra work to get what they
want, if what they want is something other than the documentation
notebook.


>       And the numerous advantages of reading documentation in a more
>       suitable format and using more suitable software -- in PDF, for
>       example -- which I've listed above, coupled with the disadvantages
>       associated with having to read it in the existing Mathematica
>       documentation formats, just make the choice a no-brainer, IMHO.

Clearly we disagree here.


>> >[...]
>> > [Did I add, that selected pages or sections of documentation in PDF
>> can
>> > also be printed out, if you'd prefer to have a few particularly
>> relevant
>> > pages of the documentation sitting on your (physical) desktop, beside
>> > your keyboard -- where you can just glance over at it, without having
>> to
>> > close or open anything on screen.]
>>
>> Last time I checked (which was today), one can still print Mathematica
>> notebooks. This would apply to e.g. Help browser pages.
>
>       Last time I checked, most of the rest of the software world --
>       indeed most of the rest of the world, period -- was supplying its
>       documentation in downloadable PDF format; and even the authors
>       and distributors of many books and manuals sold on paper were
>       also including a full CD of the full content along with the
>       purchased book (and were also continuing to write, publish,
>       and successfully market these books and manuals).  Could it
>       be there's a reason for this . . .?

One can get documentation in a "conventional" web-based form. Quick
example: From the Help browser notebook page for, say COntourPlot, at the
top right there is a URL button. Click and it gives a dropdown menu with a
"Go to web url" option. If you click that, you get to the web page below.

http://reference.wolfram.com/mathematica/ref/ContourPlot.html

So now your documentation is in a standard format, of a web page, and you
are on a site from which you can navigate. For purposes of documentation,
web pages seem also to be well received, and are more readily navigated
than pdf files (since one can change pages without requiring hot links).


>       Or are you suggesting that it would be too difficult for Wolfram
>       to serve different portions of its customer base, who might have
>       varying needs or preferences, by just setting up an automated
>       process to convert its documentation into PDF files on its web
>       site, which users could then access and selectively download,
>       when, if, and as they needed?

I do not know if this would be difficult. If it is at all difficult, it
might or might not be worth doing. The down side is of course the
opportunity cost, in that it would very nearly replicate existing
functionality (the viewing and navigability parts covered by html-based
documentation, and the printing by notebook printing), at the expense of
different development and/or documentation work. Not my call, but I myself
see that as a significant issue.

I will say that I agree there is a need for some amount of pdf-based
documentation, specifically of the virtual book. I asked about that in
house several months ago, and was told it is under discussion. I do not
know what are the eventual prospects.


>> In the Help browser notebooks one can also click on URLs to the
>> corresponding (html) web pages, bring them up, print them, etc. Maybe
>> not suitable for framing (unless you print on really good paper). But
>> useful all the same.
>
>       The endless and aimless clicking through literally hundreds if
>       not thousands of infinitely branching links, trying to find
>       out what is in Mathematica's documentation, or where it is,
>       within what often seems an infinitely expanding tree structure --
>       or, later on, attempting to get back to something that you
>       noted earlier on and now realize you want -- is in fact _the_
>       single most aggravating and disfunctional aspect of the
>       whole system.

The web based documentation has quite standard methods of navigation,
including the usual "back" button and bookmarking capabilities. I doubt
this is substantially different from documentation for any other product.

The need for branching follows from the very obvious need to handle the
sorts of thing you yourself have complainend about long and often, to wit,
that Mathematica is a complex product, requiring substantial
documentation. And I would expect that the documentation will grow, not
shrink, as more gaps get filled over time. Moral: "You can get what you
want, and still not be very happy." (Might be a very old quote; I think I
first saw it in an old issue of Cerebus the Aardvark.)


Daniel Lichtblau
Wolfram Research





  • Prev by Date: Re: Looking for more Mathematica online user groups/forums
  • Next by Date: Re: Mathematica documentation - for newest and older versions
  • Previous by thread: Re: Any way to make help browser remember the last
  • Next by thread: factor out a term to cancel in a fraction