exportOutDirName relative to source file location

[luxaritas]

Loving the extension, but one thing that I still can't get right is how to properly set the output directory, even looking at #82 and such.

What I'm looking for:

a/
    b/
        diagrams/
            source/
                mydiagram.puml
            out/
                My Diagram.png

If I just set exportOutDirName to...

• out, I get out/a/b/diagrams/source/My Diagram.png
• ./out, I get out/a/b/diagrams/source/My Diagram.png
• ., I get a/b/diagrams/source/My Diagram.png
• a/b/diagrams/out, I get a/b/diagrams/out/a/b/diagrams/source

Is there an existing way to do what I want? exportOutDirName sets the root of output path, but even with exportSubFolder as false, all directories are still copied (just no separate directory based on the diagram source file name). Maybe an extra option is needed to control the behavior about how directories are copied?

[qjebbs]

The extension has to deal with general use cases. If your logic implemented, where should I put output for a file out of diagrams dir, like a/source.puml? Because user will do this, for sure.

PS: Does multi-root workspace meet your need? One for your code, one for diagrams, and you organize them in same window.

[larslue]

Any chance the output dir could be defined relative to the source file. In the example above it would be

exportOutDirName: "../out/"

which would create

diagrams/
    source/
        mydiagram.puml
    out/
        mydiagram.png

In my case I want to commit both the source file and the exported diagram to Github. So I want the export in the same folder. It would be

exportOutDirName: "."

myrepo/
    docs/
        diagram.puml
        diagram.png

[qjebbs]

@larslue, About your proposal, consider dir structure like this:

diagrams/
    source/
        dir1/
            mydiagram.puml
        dir2/
            mydiagram2.puml

It would be:

diagrams/
    source/
        mydiagram.png
        mydiagram2.png
        dir1/
            mydiagram.puml
        dir2/
            mydiagram2.puml

To your case, try:

exportOutDirName: "."
exportSubFolder: false

[larslue]

Thanks, this is what I wanted. For unknown reason it was ignoring the parameter

exportSubFolder: false

yesterday and kept putting the files in the "out" folder relative to my workspaceRootFolder.

[maxaxehax]

@qjebbs For the most flexible configuration (very similar to the original one requested on this issue), I still think having the option to set an export path relative to the source file would be quite useful. Then, for the structure which you proposed last, one could use the settings:

 exportSubFolder: false,
 exportOutDirName: "../"

Even better would be to split exportOutDir into three settings: exportBaseDirName: string, exportWithFolderHierarchy: boolean (true: current behavior; false: the folder structure above the source gets ignored and the diagram just put in the baseDir) and exportRelativePath: string (path relative to source files, to enable putting diagrams still under the baseDir but then in a subdirectory which can differ from where the sourcefile is) for full control. I am unable to think of any use case which could not be realized by having these options.

Context for my slightly more complex use case: I also use a code generator from my uml code, and thus I have the domain model split into many (includable) .class.puml files which can be included elsewhere. Then I place my .diag.puml files at the proper place in the folder structure.

[qjebbs]

@mhaaz According to your proposal, what should I config, if I want follwing result?

diagrams/
  out/
    source/
      dir1/
        mydiagram-1.svg
        mydiagram-2.svg
      dir2/
        mydiagram2-1.svg
        mydiagram2-2.svg
  source/
    dir1/
      mydiagram.puml
    dir2/
      mydiagram2.puml

Current config to get above result:

exportOutDirName: "out"
exportSubFolder: false

[maxaxehax]

Hi @qjebbs ! Thanks for the response and interest in my proposal. Assuming I understood your example correctly, I think this could be configged as follows:

// All exported diagrams are in this folder or one of its subfolders
// Leave empty or "." for using the root folder of the workspace
// (e.g. to keep diagrams together with their sources)
exportBaseDirName: "out/",

// Recreate folder structure of source files inside base dir ( the  .../source/dirN/... part)
exportWithFolderHierarchy: "true",

// Do not move the exported diagram relative to where the source
// is in the folder structure
exportRelativePathFromSource: "."

The option names might not be that elegant, I'll gladly put some more work into them if you think they are confusing or need improvement. In particular, just as @LFP6 did, I originally though the existing option exportSubFolder did what I want exportFolderHierarchy to do, so we could probably change both names to make it clearer. For example, exportSubFolder could be exportFolderPerFile instead.

One small addition: If exportWithFolderHierarchy == false" (meaning: all diagrams get put directly into the baseDir and don't reproduce the folder structure containing source files), the third option exportRelativePath could just be ignored.

[qjebbs]

I am not sure if I get it right. exportRelativePathFromSource (suppose it's .) decides where to create exportBaseDirName(suppose it's out), according to the name of the setting, I guess we should create out folder around the source file (to below example, we got many out beside many source files), not exactly what I want in my last post.

diagrams/
  source/
    dir1/
      mydiagram.puml
      out/
        mydiagram-1.svg
        mydiagram-2.svg
    dir2/
      mydiagram2.puml
      out/
        mydiagram2-1.svg
        mydiagram2-2.svg

[maxaxehax]

I'm swamped at work at the moment, but I have started writing a lengthy post with examples to hopefully clarify exactly what I mean. I just wanted to let you know I'll get back to you in a couple days 😉 (and edit this post to make it meaningful)

[trycontrolmymind]

I think, that settings:

exportOutDirName: "."
exportSubFolder: false

must be default, 'cause /out/ is not familiar behaviour

[qjebbs]

@trycontrolmymind To programmers, export to out helps better compatible to source control scenes. If you don't need this behavior, change it in user settings

[BladeWise]

What I find counter-intuitive is the fact that using exportOutDirName: "." will actually set the path to relative to the input file, but using a relative path like exportOutDirName: "./out/" will act as the default and create an export path that is relative to the workspace root.

My scenario is like this

Project Folder/
  docs/
    analysis/
      diagrams/
        src/
          architecture_overview.wsd

and I would like to end up having something like this

Project Folder/
  docs/
    analysis/
      diagrams/
        src/
          architecture_overview.wsd
        out/
          architecture_overview.png

in other words, I would like the out folder to be on the same level as the src, and eventually keep the underlying directory structure.

[qjebbs]

@BladeWise, how about this (kind of like tsconfig.json):

diagramsRoot: "docs/diagrams/src"
exportOutDirName: "docs/diagrams/out"

diagramsRoot specifies where the diagrams sources located, while exportOutDirName tells where to put exported files, which keeps same structure to diagramsRoot.

But the extension will refuse to export diagrams outside the diagramsRoot, because I don't know where to put exported files for them.

[BladeWise]

@qjebbs, it would be fine, even if I would probably prefer something like

{
    "plantuml.diagramsSearchPath": "docs/diagrams/src/**/*.wsd",
    "plantuml.exportOutDirPath": "docs/diagrams/out/**/",
}

in other words, to be able to use wildcards to determine if the full tree structure should be preserved, only the top node, etc... The idea would be to process each selected diagram path through the exportOutDirPath, replacing the constant part and expanding (eventually) the wildcard part. But maybe it's just overkill...

[chipbite]

What I find counter-intuitive is the fact that using exportOutDirName: "." will actually set the path to relative to the input file, but using a relative path like exportOutDirName: "./out/" will act as the default and create an export path that is relative to the workspace root.

This is a good and valid observation, I think. (I don't have a solution proposal though.)