Scripting Examples - New Content

[sifran-github]

I created a PR: #139
(merged. you can see the new section here: https://docs.freeplane.org/scripting_examples/_scripting_examples.html)

It contains a new section with scripting examples by category. I divided it into:

• Node - Examples related to one node.
• Map - Examples related to multiple nodes / entire map.
• Others - Other Examples if this category will get big, it should be split more.

I added several examples.
I didn't make one huge page because the categorized structure is much more organized. ChatGPT will be able to read this structure as well.
I didn't merge it yet, to let other people view it. its not critical code or something so I might merge it soon...

I think that the next step will be to add more examples on each topic, and also to go over the existing "scripting" content, and extract the relevant information. The current "scripting" documentation contains a mix of general information and some examples. For example, in this page: https://docs.freeplane.org/scripting/Scripting.html there is a part about links which I consider "example" and I plan to extract into the new examples section, and a part about Execution modes which is a general information and should stay there.

What do you think?

[sifran-github]

I encountered 2 issues during this process:

Issues 1 - Folders in mdbook

Basically this: rust-lang/mdBook#483 (comment)
mdbook doesn't support a nice looking "folder", that doesn't have a page with content. It is possible to create one, but it looks like a missing item.
I do think, for example, that https://docs.freeplane.org/scripting/Scripting.html should be moved to another page, and it should not stay the content of the main folder of Scripting.

So there are several solutions:

1. Use folders that looks like missing items.
2. Fix the looks of these folders with css/js.
3. Use simple pages for folders. like I did in my new PR.

Issues 2 - Error running mdbook with "mdbook-open-on-gh" extension

When i ran mdbook with the "mdbook-open-on-gh" extension, i got this error:

[INFO] (mdbook::book): Book building has started
thread 'main' panicked at .cargo\registry\src\index.crates.io-6f17d22bba15001f\mdbook-open-on-gh-2.4.1\src\lib.rs:113:47:
called `Result::unwrap()` on an `Err` value: StripPrefixError(())
[ERROR] (mdbook::utils): Error: The "open-on-gh" preprocessor exited unsuccessfully with exit code: 101 status

I'm not sure why but this extension tries to get some value of git_root and cannot get it.
i had to disable this extension by removing the following lines in book.toml, and it worked:

[preprocessor.open-on-gh]
command = "mdbook-open-on-gh"
renderer = ["html"]

But i wonder if this can be fixed.

my version of mdbook:

>cargo install --list
mdbook v0.4.36:
    mdbook.exe
mdbook-open-on-gh v2.4.1:
    mdbook-open-on-gh.exe
mdbook-toc v0.14.1:
    mdbook-toc.exe

[EdoFro]

Sometimes in my posts in Github I use <details> sections.

Maybe this in an alternative to also set the doc structure.

something like this:

<details><summary><h2>My hidden section <h2> </summary>

### it supports Markdown

**List:**
- item 1
- item 2
- item 3

**code:**
    ```groovy
    def a = node.text
    return a.reverse().toUpperCase()
    ```

**Table:**

|chapter|pages|
|---|---:|
|A|12|
|B|23|
|C|7|


</details>

results in this:

My hidden section

it supports Markdown

List:

• item 1
• item 2
• item 3

code:

def a = node.text
return a.reverse().toUpperCase()

Table:

chapter	pages
A	12
B	23
C	7

---

BR,

Edo

[sifran-github]

Really nice. I didn't know about it.
I checked and it is possible in mdbook, but you need to have the header with inline display style, like this:

<details><summary><h2 style="display:inline">My hidden section <h2> </summary>

But anyway it is a different topic than the issue with the folders. here you can see an example of how items in mdbook without pages look like. It is an issue that is open since 2017, so they probably will not fix it soon.

[EdoFro]

And what about using the link to the first item as a link for the "folder" item (when the "folder" item has no own document)?

something like (using the same example as your link):

# Summary

- [mdBook](README.md)
- [Command Line Tool](cli/cli-tool.md)
    - [init](cli/init.md)
    - [build](cli/build.md)
    - [watch](cli/watch.md)
- [Non existing top level](cli/serve.md)  <--- here!!
    - [serve](cli/serve.md)
    - [Non existing]()
    - [test](cli/test.md)
- [Format](format/format.md)
    - [SUMMARY.md](format/summary.md)
    - [Configuration](format/config.md)

[sifran-github]

Interesting. I checked this idea, and technically it seems to be working. It just highlights also the folder as "active" once you view the page, but its ok.

There are some rules in this mdbook application... for example if you link to a non-existent page, it will auto-create it... but for multiple links to the same page... maybe its possible. Anyway I cant think of a reason that it might make issues right now, but I don't know a lot about mdbook.

[sifran-github]

Another small issue is that I am having is that in my fork of the docs repository, I get error about the job "pages build and deployment".
Can someone guide me on what I should do with it?

[sifran-github]

I merged it into the docs. you can see the new section here :
https://docs.freeplane.org/scripting_examples/_scripting_examples.html

Its not a critical code, we can always change it back if needed.

Comments will be appreciated :)

[euu2021]

I like this idea. So, right now, it seems that we have two levels of organized examples:

• Methods Reference: a very simple example of each method, just to show how the syntax works.
• Scripting Examples: more complex examples, but still very systematically organized according to typical Freeplane categories (attributes; icons; selection; etc).

Maybe, a useful task is to go through the scripts from the Scripts Collection and move into the Scripting Examples the ones that can fit nicely in a category.

[sifran-github]

Yes. in general i want to go over all the scripts, from all pages, and extract examples into the new section that I have created. Usually these will be much simpler examples than the one in the scripts collection.

Regarding the scripts collection, most of the scripts there are too big to be included in the new "examples by category". I named the section exactly like that in order to separate between simple script examples (should be there) and big complicated scripts that can almost be an add-on (should NOT be there).

[sifran-github]

regarding, the Method Reference: maybe it will be a good idea to itegrate it into the code itself, in order for it to go to the API documentation?

for example:
this:
https://github.com/freeplane/freeplane/blob/1.11.x/freeplane_api/src/main/java/org/freeplane/api/NodeRO.java#L281

turns into this:
https://docs.freeplane.org/api/org/freeplane/api/NodeRO.html#getText()

[euu2021]

regarding, the Method Reference: maybe it will be a good idea to itegrate it into the code itself, in order for it to go to the API documentation?

Yes, Edo suggested it, too.

I'm not a big fan of keeping multiple copies of the same information on different places, because it makes maintenance more difficult. But, in the future, we can make tests to see what works better for ChatGPT.

[dpolivaev]

@sifran-github In #135 (comment) I have suggested that all groovy examples are added to https://github.com/freeplane/docs/blob/main/src/docs/scripting/basics.groovy or https://github.com/freeplane/docs/blob/main/src/docs/scripting/reference.groovy. I think that using real groovy files makes it easier to have working examples and to modify them.

Now I have got an impression that you are not following this idea. I would like to understand if you are aware of this suggestion an what you think about it.

[dpolivaev]

I found that if we click on the printer button on the Freeplane doc page, it allows send the whole content to any printer, particularly to generate PDF. I have added it to FreeplaneTutor GPT instead of the old text file where I just merged all md files.

Obviously, we could also copy-paste text from it.

Because of the bug in mdbook, it seems that the navigation panel should be closed when you use this button.

[dpolivaev]

I found out it does not work well because it breaks text flow

[sifran-github]

It is a strange behavior. usually print should print the current document, not everything. but ok...

you updated chatgpt with it? what is the link again?

[dpolivaev]

Yes, I updated, but I am going to revert.
https://chat.openai.com/g/g-CkkQa1aEP-freeplane-tutor

[sifran-github]

oh ok. yeah we need to understand how to feed ChatGPT in a good way. but its just step 2. in my opinion, step 1 is to build a good and organized documentation...

its ok to do step 2, but I just don't think that step 2 should dictate how we build step 1...

Regarding how exactly to convert it... I'm not sure what ChatGPT needs. I could experiment with it but I thought that he can read pdfs and everything. if its not the case, maybe we should just combine the md files, or even just the code parts of the md files?
should search some tutorials on how this machine wants to be fed.

[sifran-github]

I added more scripting content to the docs: #141.

One script that I added is simple output window, that can help programmers when showing some calculation result. i wrapped it in a simple to use function: https://docs.freeplane.org/scripting_examples/gui.html

This is the most "complex" script that I will add to the "Examples by category" section. All other scripts will be simpler.
The reason behind it, is: this category is not intended to have complex application like in the scripts collection. The script that I added to the new category has only one intended function, and that's it.

this is another example of what should go into the new category: https://docs.freeplane.org/scripting_examples/traverse.html
as you can see, its not a full program, its just some simple scripting examples that shows you how to traverse the mind map.

That is my goal with this category, to show simple examples of each feature.

In the future I will change the structure of these existing pages:
https://docs.freeplane.org/scripting/Scripting.html - split into several pages & extract examples.
https://docs.freeplane.org/scripting/api-groovy-tutorial.html - split into several pages & extract examples.
These pages contain a mixture of "getting started guide", and examples. I also think that it is better to split them to different pages.
also, https://docs.freeplane.org/scripting/Scripts_collection.html - extract only the simplest examples into the new category.
and more.

if you have any feedback, let me know.