uno, python scripting, macro management window & user experience

Dear dev-list.

TOPs:
[1] Summary: What I'd like to improve - this requires a wiki which is
    why I'm asking here cause I need your help.

[2] What made me write this mail - my journy (only read if you have
    time)

============
[1] Summary: What I'd like to improve - this requires a wiki which is
    why I'm asking here
============
I'd like to improve the user experience for new users who try to get
started with scripting LibreOffice. And that requires better
documentation. Because I'm new to LibreOffice development I need your
help getting started.
Because things change I'd suggest creating a wiki or
reuse an existing one which tells about the most basic steps.
Use a wiki so that. However this requires that the wiki can be found.
This means adding a link to it on api.libreoffice.org

The wiki should help getting started and choosing the most simple way.
Thus it has to talk about:
JS vs Basic vs BeanShell vs JavaScript running in LibreOffice vs
connecting by tcp/ip.

More detailed list about wiki contents I'd like to add / see:

1) Talk about pro/cons of the different scripting solutions - so that
its easier to choose the right one. And this should be comprehensive
enough that you know that Basic does not have trivial str_replace like
functions on its own. (just saving a .odt as .html requires google
because you have to replace .odt by .html in the url)

Talk about what the goals of this Basic dialect is (eg be as similar to
MS VBA as possible - or something else?)

Point to an introduction about language features. A link is enough.

Talk about pro/cons running in LibreOffice, having XSCRIPTCONTEXT is a
very strong argument because it provides getDocument()!
But this is not obvious to new users.

2 and 3: For each language:

2)
  Create a dead simple introduction so that you can get started with
  your *own* script doing simple thing such as "save to file", access
  active cell's content and the active document.
  For python this requires talking about the "LO user configuration
  directory". You can make looking / having to know about it obsolete
  by renaming "My Scripts" to something useful such as
  "$HOME/.libreoffice/.." - and you don't even have to start looking for
  documentation.

  Provide this example using the "in libre office scripting support" and
  connecting via TCP/IP so that you understand the difference and know
  which one will serve you best.

  If its hard to provide both ways - its a hint that some library
  support is missing.

3) make sure that this wiki can be found easily by visiting the official
api.libreoffice.org page.

Then people like me can easily pick up scripting without having to know
things which have "traditionally been that way - but which are hard to
find - but could be solved by 5 wiki pages".

4) If there is dev time available: Don't gray the python buttons, make
them show a message box like "for python see api.libreoffice.org".
Then the user get's the feeling "thanks, how kind of you for helping me"
compared to what he get's now which is "Is LibreOffice that buggy?"


I hope you get the points - and agree that this all would improve the
user experience when trying to get started with scripting very much.

Sincerly
Marc Weber


============
[2] What made me write this mail - my journy (only read if you have
    time)
============

Some things were not obvious to me at the very beginning - and lead to a
bad experience which I'd like to change for the future, because I love
open source myself.

Right now there are many different sources of knowledge and its not
always easy to understand which are up to date which leads to a lot of
try and error.

You'll find a longer description here however I'll write a summary
below.

STEP 1) try basic
https://bugs.freedesktop.org/show_bug.cgi?id=5628://bugs.freedesktop.org/show_bug.cgi?id=56289
Tools -> Macros -> Organize Macros -> Libre Office Basic

With experimental macro recording enabled its possible to get started
fast - until you need trivial functions such as "str_replace".

With some googling you can find them - but soon you think - let me use
python.


STEP 2) try python because it has more support for trivial functions
Let's try again
Tools -> Macros -> Organize Macros -> Python

You get a window - you find the samples (which you also find at source
easily) - but you don't know how to write your own scripts. The buttons
"edit" are grayed.

STEP 3) get help
Next try: Use "Help". You get to a page having the headline "Macro".
You notice, that its not going to help you, because it only describes
what the grayed "edit" button does.

STEP 3.1 and 3.2
I'm a dev myself - not an average programmer. I'm smarter than that. At 
the bottom there is 
A) "Macro programming in Libre Office" 
B) "Assigning Scripts in LibreOffice"

STEP 3.3
Yeah. Looks like A) is what I'm looking for.  Quote (See api.libreoffice.org)
B) 4. python, no details given, also points to api.libreoffice.org

Great - I finally know where to have a look at:

STEP 3.4
api.libreoffice.org, let's try that. Finally I'm there.
There is IDL, Java, C++, "Development Tools" and "Examples".

At this point you wonder whether the Java api is the same as IDL and C++
or whether there are small but mattering differnces.

STEP 3.5
Anyway, let's try the Examples. Yeah - there is a python sample:
"ToolPanelPoc". And it does have a README:
http://api.libreoffice.org/examples/python/toolpanel/readme
quote:
"- install it"

How do I install python scripts? The buttons are grayed!

STEP 4 - try a different way, use google
Ah - there is soffice -socket something - so maybe I have to connect via
TCP/IP. Greate - then I can use my favorite editor: Vim and the python
REPL, too. Next problem: there is no XSCRIPTCONTEXT - and the
getCurrentDocument or such always failed for me. At this point I feel
like "I should be using Microsoft Office".

Then there was the bug tracker - and that was down for as short period
of time.

I still didn't give up - I managed to get the (uglier) Java uno samples
working - however they are very verbose. Java is very much typed - the
samples are not - and they all redo the same: create a connection etc.

You write more than 8 lines till you get to the point doing what you
want. You start wondering - why is there no function I can call?
All I want to do is:

CONTEXT->getCurrentDocumentAssumingItIsCalc->getActiveSheet()->isCellMergedAndWhichCellsAreMerged()

I can express it in one line - but coding it in Java lead to a lot of
googling - and the code I ended up didn't even work.
The final solution was: Don't use uno, export to HTML - but you still
get the point. I have a very bad user experience.

Let's try the competition: google for "merged area cell Excel basic"
first hits shows a solution:

  Range(Foo).select
  If ActiveCell.MergeCells Then
  MergedInfo = ActiveCell.MergeArea
  MergedValue = MergedInfo(1, 1)
  End If

I didn't try it - but it looks promising. At this point I got the
feeling having wasted many hours - still worth it - because I know that
programming uno is hard (which it should not be!)

The conclusion eventually is that I might consider using MS Office
instead - and that I start wondering whether LibreOffice is an
alternative (which it should be)

Sincerly
Marc Weber