Diagrams and graphs

[deviator]

What about generation PlantUML with some settings ( for example show fields or not )? It can be a good part of documentation. It's planed?

[kiith-sa]

Having diagrams (class hierarchy, members, call graphs, class dependency graphs, maybe more) would be useful and I would like to eventually do it, but I intend to keep harbored-mod D only with no dependencies on Java or any other language, so I don't plan to use PlantUML in particular. I also think having exact formal UML is not a good idea (too rigid, not well designed for a language like D), though some parts of UML could be used just to keep it familiar.

It shouldn't be too hard to write some simple SVG generation functions (line, rectangle, text, arrow should be enough) - and that would be enough as a base to start drawing simple graphs. That said, I don't plan to do this in near future (at least a year) because there are still more important things to do and I'm also working on other projects.

[kiith-sa]

Renamed the issue to better explain the actual goal (and since I don't intend to use PlantUML in particular)

[deviator]

Have you found suitable variant textual description of diagrams and graphs, or it must be created in future special for D?

[kiith-sa]

AFAIK there is no such library in D at the moment.

However, I would probably go for a simple SVG drawing library and then directly generating graphs from e.g. SymbolDatabase data in harbored-mod. A full blown text to UML library would be a lot of work and most of it would actually never be used. (and again, I don't think plain UML is a good fit for D)

[deviator]

I really understand that plant UML isn't good for D, because I use it for desctiption my project. Result in some places does not represent my ideas, that are implemented in code. I think only that plant UML is good as concept: intermediate flexible textual desctiption. Similar description can be rendered using different algorithms with different settings to different formats. This allows to break the link between the generation of information for a graph and its construction. I just wanted to convey only this idea.

[kiith-sa]

I didn't mean PlantUML - I meant UML as a language in general - it was originally designed for languages like Java/C++ and a lot of D

I don't plan to support any 'diagram representation language' directly, but I plan to eventually add support for images including SVG, once that is in it should be possible to e.g. generate such images externally and reference them from DDoc.

I plan to (not in near future) generate diagrams within generated documentation, but I don't plan to export them in any way (at least in near and medium-term future) - that would require formalizing them - I expect I will need to do a lot of informal experimentation before I get something that "works for D" and formalization would make that harder/impossible. But even then I think exporting such format would be better handled by a completely separate tool e.g. based on libdparse.

One idea I got from this is that it might be good to support special text block that would be processed by any external tool specified by the user. That would allow doing this seamlessly but make it the user's responsibility to e.g. specify how to use that tool.

E.g. something like:

_external-plantuml:   //Repurposing DDoc section syntax to avoid adding more syntax

plantuml source here

the _external prefix would be generic and could be followed by any name, and in hmod.cfg the user would have to explain what e.g. plantuml actually means and how to handle it (this will take a lot of work to get right; because e.g. some tools might generate an image that would be inserted, some might generate HTML that would be inlined directly, some might generate files that would be linked (e.g. PDF), etc.

Also, a completely separate "external tool description file" might be better than using hmod.cfg directly.

This is just a far off idea, I'll add an issue for it but I don't expect to implement it very soon