Scripts documentation

[euu2021]

In the last meeting, @sifran-github raised a question regarding the documentation of things related to scripting. This is a topic that I got interested, and I would like to contribute.

I'm still in a very basic level, but I'm interested in learning about scripting, and I think I can work on the basic parts of the documentation, as I learn about them.

I would like to create a simple example for every method of the API, like they do in the Autohotkey documentation (e.g., see the end of this entry). For me, having those examples is very helpful, because I can right away have an idea of how the command can be used. For example, in the Freeplane API there is the setStyle method, but I don't know how to use it in a script, and I can't find examples in the forums. I don't know where it would be the appropriate place to put those examples, though.

So, I would like to know what are the plans for this part of the documentation.
BR,

[macmarrum]

@eu2021, sifran and anyone else interested, please feel free to use https://freeplane.github.io/wiki/#/tutorials/freeplane-api-groovy/index as the starting point for your work.

At the bottom of the page there is the icon [📝] that leads to the GitHub repository for the file.

You can fork the repository, creating your copy under your user on GitHub → https://docs.github.com/en/get-started/quickstart/fork-a-repo
You will then be able to add content to your repository. Once you are satisfied/ready, you will create a Pull Request to integrate your changes to the main repository → https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork

In case of any doubt, please feel free to ask

[euu2021]

This is the sequence of events that explains my current situation:

-I wanted to include a simple operation in a script: set the selected node style to a style that I had previously created.
-Inside that Api I found the page Interface Proxy.NodeStyle. Inside it, I found the method setStyle.
-I tried to use setStyle, but failed, as I said here.
-After some time, I noticed that it's much easier to create an Autohotkey script than a FP script. Thinking about it, I found why: in the Autohotkey documentation, each command have a simple example of the command being used in a concrete situation, so I can simply grab the line as a premade block that can be combined with other premade blocks in order to make the sequence of action that I want. So, I wanted to have that for FP, too.
-I explained my intent on this thread.
-Macmarrun said I should have the link above as my starting point.
-I'm trying to access the link. I don't know what was the content of the page.

[macmarrum]

The page got moved to https://docs.freeplane.org/#/attic/new-wiki-initiative/freeplane-api-groovy

[dpolivaev]

And currently it seems to be empty and at the wrong place. Where should it go to?

[macmarrum]

The page is empty so that eu2021 or sifran-github can start creating content.
It is in attic because it is incomplete.

[euu2021]

Ok, I understand. I will make some tests. Thanks,

[quickfold]

@eu2021 , I'm not sure if this is the same thing that @macmarrum is pointing to, but the old wiki in MediaWiki format had a lot of information/pages about scripting. You should take a look there if you haven't already.

[euu2021]

Hi, quickfold

Yes, the Wiki pages are my main reference when creating a script. There is
-an introduction to scripting page, which is a step by step guide on how to create simple scripts.
-a scripts showcase, which is useful when the user wants to see how a part of the api can be used
-other pages, explaining things like how to use other languages beyond groovy

Besides that, there are also the API pages, which are generated by clicking in Help>Freeplane API , inside Fp. This is a"technical reference" place where it is possible to find a complete list of Fp codes that can be used in scripts.

So, the path that I usually go through when creating a script is like that:
-look in the scripts showcase to see if there's a script or part of it that does what I want;
-search in the API for something that sounds remotely useful for my situation. Then I search in the forums for examples of that being used. If I don't find examples, then I play with it until I understand how it works, but it can be frustrating, because those things sometimes are not very intuitive (for example, try to use setStyle). I think that this is where it would be useful to have a simple example showing each piece of code in use.
-ask for help in the forums

There are other things that can be done to improve the scripts documentation, but that's the low hanging fruit that I see right now.

[euu2021]

Just to test the format, I created an example script for each method of the IconRO and Icon interfaces. I put it in a table: https://github.com/eu2021/docs/blob/main/attic/new-wiki-initiative/freeplane-api-groovy.md

I like the idea of creating a gigantic table with all the methods, because the user can follow either paths of:

• Find the method in the API
• Search the method in the documentation, where he will find the simple examples in the table, and also examples in the scripts collection

Or

• Use the table to quickly find methods
• Search in the API for more details

The other possibility would be to insert the examples directly in the API, like already sometimes happens, like:

Anyway, I will keep creating in this table format, and later it can be used in other ways.

[macmarrum]

Cool. I'm looking forward to seeing it evolve.

BTW, please keep in mind the difference between Groovy-style and Java-style coding for your examples, e.g.

• c.statusInfo = node.icons[2] Groovy style
• c.setStatusInfo(node.icons.getAt(2)) Java style
• c.statusInfo = node.icons.getAt(2) mixed style

See also https://docs.groovy-lang.org/next/html/documentation/#properties

[euu2021]

Interesting. I will read some things to see if I understand it better. It seems that the key here is to understand this properties X getters and setters thing.

In the Help->Api Generator there is this information:

And, in the Scripting page:

---

I will read the Scripting page carefully to find the exact parts where the explanation jumps too much, leaving a gap in my comprehension. I will write a report about it, so I can later use it as a reference for improving the scripting documentation, after I finally understand those ideas.

[euu2021]

By chance, I found this very interesting discussion.

The idea that Quinbus is exploring there seems to be similar to what I have in mind when I talk about premade blocks of code that an non programmer user can use in order to create simple scripts.