[Paraview] documentation

[Ken Olum]

Thanks for the quick answer to my question about installing macros.

I'm writing now because I'm very unhappy about the state of the
documentation.  Let me say that paraview is a great program and it
enables me to make beautiful visualizations.  So I am reluctant to
criticize the developers, but it really is remarkably difficult to
learn to use.  It's bad enough that I'm seriously considering
abandoning paraview and using something else.

I hope that you would like to have a product that new users can learn
to use without too much frustration, so let me go through my recent
experiences to show why I'm so frustrated.

I would like to display stereoscopic images.  So I looked in the
Paraview Guide for any mention of stereoscopic display.  It isn't
there.  I tried the online help, but there is no index, so I can't
search for it.  I tried various help topics, but didn't find anything
relevant.

So I went to the net.  I couldn't find any documentation for stereo,
but at least there is some archived discussion, so I learned that
there is a "--stereo" command line switch.  So far so good, but how
can I control how it renders the stereo?  I got a list of commandline
options, and there is a set of modes.  But what are they?  What do the
options mean?  I have access to a "visualization wall" which sends
side-by-side display of the stereo frames to overlapping
super-anaglyph projectors.  Can I use it?  How?

And what about turning it on or off dynamically?  There doesn't seem
to be any control of it once paraview is running.  But I managed to
learn, again by looking through the archived messages to this list,
that the stereo selection is an option of the viewer, and I was able
to turn it on and off using the python shell.  Excellent!

So then I thought, "Can I make this into something I can click on?"  I
see that there is a "Macros" tab, and a macro is just what I want.
Back to the online help.  No mention of macros.  Back to the book.  No
mention of macros there either.  I didn't mind paying $80 for this
book, since the software is free, but at least I thought for $80 it
would answer my questions.

OK.  Back to the net.  Aha.  There is a Wiki page on "Python GUI
Tools".  The first topic is Macros.  What does it say?  "The
management of macros is done inside the Macros menu".  Click on
"Macros".  The only item is "<empty>".  Oops.

What does it say next?  "Macros allow the user to define a Python
script as built-in actions that become accessible from the Macros menu
or directly inside the Toolbar."  Just what I want!  Great!  But how
do I do it?  "Once a local file is defined as a Macro the given file
is copied inside the user specific ParaView directory."  OK, but HOW
do I define a local file as a Macro?  Nothing further is mentioned in
this file.

So I posted to this list, and right away I got an answer.  Thanks!
That's great, but should I really just post my question here first?
It seems I ought to try to answer my questions before bothering
everyone, but I'm not having much success.

In any case, while the answer (from Sebastien Jourdain) answered my
question perfectly, he also said "We recently changed the Macro menu
and the way that macros are managed.  The wiki explains the new way."
Does it?  All I could see was what I quoted above, which does not
include any mention of how to define a macro.  Maybe if I actually had
the new version it would be obvious, but I certainly couldn't figure
it out from this file.

Anyway, shouldn't the documentation correspond to the latest version
that one can download from the download site?  Or, at least, shouldn't
it say that it corresponds to a later version and make it easy for me
to find the documentation corresponding to the version I have?

Again, I'm sorry to be so critical (and so verbose), but I beg you to
consider the plight of new users and make things not so frustrating.

                                        Ken