Is it possible to create on each folder a Readme.md file?

[The-Lum]

💡 Here is a poll for Readme.md creation.

[Potherca]

I think the question is, what should be in the file? @The-Lum If you have some idea about that, I could set up a first-draft MR to discuss things further.

[The-Lum]

FYI, here is a first PR:

• feat: add README.md on each stdlib folder #113

[Potherca]

As a consumer of the INFO files (for instance in plantuml-stdlib/update-stdlib.sh), I definitely prefer YAML frontmatter over MD tables.

On the topic what should be in the file, I am still unsure. The README.md already in the projects themselves would not translate well into plantuml/plantuml-stdlib.

So what information should be present in the README and where should it come from?

[kirchsth]

Based on the last changes we have the details in the readme.md, but in the code itself I cannot query it (like %version() for PlantUML).
Shouldn't we add calls like %libversion("C4"), %libversions(), %libversionjson("C4") and %libversionsjson()?
And the json version contains only filled fields.

Corresponding samples see below:

[The-Lum]

Hello @kirchsth,

Yes it is plan...

Here is the imagined roadmap:

1. Creation of readme.md with YAML frontmatter (✔️with last PR)
2. Suppress INFO file et use of the new readme.md 🔜 🆕
3. Update & create new getter to return those values directly on plantuml ⏭️
4. Then create new built-in function to use those value directly on the preproceesor ⏭️

Awaiting all those enhancements... And in the meantime you can always use functions like:

@startuml
!$stdlib=%get_all_stdlib(detailed)
!function $libversion($lib)
!return $stdlib[$lib][version]
!end function

file f [
Version of C4: $libversion(c4)
]
@enduml

Enjoy,
Regards,
Th.

[arnaudroques]

Yes, that's what we planned to do.

The only challenge is to find the right syntax.

And here, you can help us :-)

Here are a few proposals:

• %stdlibinfo(): Returns all information about all libraries in JSON format.
• %stdlibinfo("C4"): Returns all information about the library "C4" in JSON format.
• %stdlibinfo("C4", "description"): Returns only the "description" field.
• %stdlib(): Returns all information about all libraries in JSON format.
• %stdlib("C4"): Returns all information about the library "C4" in JSON format.
• %stdlib("C4", "description"): Returns only the "description" field.

Your feedback is welcome!

[kirchsth]

Hi @The-Lum, @arnaudroques

I didn't know that PlantUML has already the %get_all_stdlib() function therefore I suggested a similar functionality.
Maybe the simplest is to add a %get_all_stdlib(full) that it returns all new properties too.

And optional add something like

• %get_stdlib(name) -> returns version number of the concrete standard library
• %get_stdlib(name, detailed) -> returns name, version, source
• %get_stdlib(name, full) -> returns all properties

If "c4" is used as stdlib-name (and not the upper case "C4", which is the folder name) we should add a stdlib-specific documentation link, and the documentation contains the correct folder name "C4". Eg. https://github.com/plantuml/plantuml-stdlib?tab=readme-ov-file#c4-library-c4-plantuml-c4 (and of course the C4 documentation itself has to be updated too ).

Another option could be that the plantuml stdlib Readme.md contains only an overview (table?) of all stdlibs with links to the stdlib specific readme.md in the subfolders.

Best regards
Helmut

PS.: related to documentation: ex. %get_all_stdlib(), %get_all_theme() and %random() is not part of the Buildin functions, maybe you can update it that all functions are listed in the grid.
Additional the table could be (grouped and) sorted.

[The-Lum]

@kirchsth

PS.: related to documentation: ex. %get_all_stdlib(), %get_all_theme() and %random() is not part of the Builtin functions, maybe you can update it that all functions are listed in the grid.

Thanks for the report, the change had just been made to the doc. (remains JSON Builtin functions):

• https://plantuml.com/preprocessing#291cabbe982ff775

Regards,
Th.

[arnaudroques]

With last snapshot 1.2024.9beta1, you can now have:

@startjson
%get_stdlib()
@endjson

---

You can get information about a specific library.
I realize that there is a confusion between c4 and C4.
So probably we should simply ignore case, so %get_stdlib(c4) and %get_stdlib(C4) would both work. This is not implemented yet.

@startjson
%get_stdlib(c4)
@endjson

---

The following calls return Strings, not Json objects:

@startuml
Alice -> Bob: %get_stdlib(c4, foo)
Alice -> Bob: %get_stdlib(c4, version)
Alice -> Bob: %get_stdlib(c4, display_name)
@enduml

This is not a final version, only a working prototype :-)
Any information added into README.md file will be available, so you can even add new key entries there if needed.

Any though?