Include block from current file?

+1 vote
asked Mar 23 in Wanted features by Chris38 (390 points)
Can a plantUML file include another block from "itself", without having to specify the actual file name?

Details:

I want to keep a single file with several diagrams, all usig a few common macros.  What I have so far is something like this in my diagrams.txt file:

@startuml(id=MACROS)

/'my macros'/

@enduml

 

@startuml

!include diagrams.txt!MACROS

/' my diagram'/

@enduml

/'a bunch more diagrams, similar to above block'/

This works great. However, the !include relies on knowing the file name...is there a way to specify "current file"? If not, would you consider adding such a feature?

The file name is usually known, but when I embed the file in a word document and double click on it, word generates a temporary file. I don't want to have to change the name in my include directives to match the temporary file name.

And thank you for this fantastic tool!

Christophe

2 Answers

0 votes
answered Mar 23 by plantuml (134,570 points)

We like the idea!

However, there seems to be an small issue.
Imagine that we define %current% to specify the "current file".

So you could have such a file:

@startuml(id=MACROS)
/'my macros'/
@enduml
 
@startuml
!include %current%!MACROS
/' my diagram'/
@enduml


However, the first @startuml block (that is, the one with /'my macros'/ ) will likely generate an error diagram when PlantUML will read it, since it defines only macros.

I think you already have the issue with your today solution (in your example diagram.txt)
How do you manage this right now ?

Thanks!

commented Mar 23 by Chris38 (390 points)
Correct, I do have that issue of an invalid first diagram. So to "kind of" solved it, I added a title to that empty diagram. Of course, this gives me a useless diagram, but a little cleaner than the error. Like this:

@startuml(id=MACROS)
title Empty block, for macro definition only
definelong TITLE_ALL(s)
  title s
  footer Generated %date%
  skinparam shadowing false
  skinparam handwritten false
!enddefinelong

' Specific settings for sequence diagrams
!definelong TITLE_SEQUENCE(s)
  TITLE_ALL(s)
  hide footbox
!enddefinelong
 
All my diagrams call one of the macros, so the invalid title gets overwritten by the real title. This gives me consistency without having to use a special command line or other external files.Of course, this might not work for everybody...

Thanks!
+1 vote
answered Mar 26 by plantuml (134,570 points)

In last beta https://www.dropbox.com/s/koo42q3d9gxw288/plantuml.jar?dl=0
We have added %filename% and %dirpath% variables.

So assuming the file "test1.txt" contains the following:


@startuml
title
Read from file %filename%
Path is %dirpath%
end title
alice->bob:hello
!include %dirpath%/foo1.txt
!include %dirpath%/%filename%.include
@enduml


and that you have in the same directory two files "foo1.txt" and "test1.txt.include"

Tell us if it helps!
(And also if you needed some more environment variable)

To turn around your title trick, we are thinking about having some @startdef/@enddef blocks that would allow to define your macros.
Then you will be able to include those blocks using some new !includedef XXX directive

I think this would allow you to do something somehow cleaner.
Any thought about this ?
 

commented Mar 27 by Chris38 (390 points)
I like the beta, thank you. It even works with file names that have spaces :)

I like the startdef/enddef too. If I understand correctly, that would allow a block with no diagram, or if some diagrams are defined in the block, they would only be generated at the point the block is included, correct?

And by the way, one big reason for that feature is that I am creating word documents in which I put the .png generated by plantUML. To keep the source file available, so I can later change the diagrams, I also "drag and drop" the .txt with the diagram definition into word. Now I can simply double click on the .txt file to open it in my editor (word create a temp file, and that is when I really need those improvements to the include functionality). From my text editor, I mapped a key to launch the plantuml viewer from the current folder. This makes it very easy for me to update the diagrams and copy/paste the new/updated png into the document.

I might have a couple  unrelated requests/issues that I will post separately.

Thanks again, great job, very useful program.
commented Mar 28 by plantuml (134,570 points)
Last beta
https://www.dropbox.com/s/koo42q3d9gxw288/plantuml.jar?dl=0
supports the following syntax:

@startdef(id=macro)
Alice -> Bob : hello1
@enddef

@startuml
!includedef macro
Alice -> Bob : hello2
@enduml

Unfortunately, the @startdef has to create an image (otherwise, the Word Addin would be lost).
Right now, the image contains only the text "@startdef(id=macro)"
It could be possible to generate a single pixel image, but I'm not sure that is is a good idea.

PS:
The drag&drop of the .txt in the word document is a good idea: maybe the Word Addin could work that way too ?
commented Mar 28 by Chris38 (390 points)
Now I am a bit confused :)

I am not sure what startdef/endef brings, maybe I am misunderstanding. Is that a combination of startuml and definelong? Can you still pass parameters?

In my example, I put all my macros in one block, using several definelong, and all of my diagrams include all my macros (initially, all the macros were in single, separate file, which gave me headaches for use in Word).

Christophe
commented Mar 28 by plantuml (134,570 points)
Sorry, I'm not very clear.
Actually, @startdef/@enddef does not bring very much.
My idea is to declare in the @startdef/@enddef all your macros.
So I'd better give you as example:

@startdef(id=mymacro)
!definelong ...
!definelong ...
!definelong ...
@enddef

@startuml
!includedef mymacro
Alice -> Bob : hello2
@enduml

It just save you from using your "title" workaround in the fist block.
Does it make more sense ?
commented Mar 28 by Chris38 (390 points)
I see, thanks. I like it.
 And this works only if the macros are in the same file, correct ?(removing the need for the new variables you provided, in that particular case).
The latest beta gives me error though...The first error is "empty description" (for the startdef block). If I add a "title" line in the block, then that error clears. But then I cannot call my macros. This is an example, simplified to a single macro, maybe I just have a typo...
@startdef(id=MACROS)
!definelong TITLE_ALL(s)
  title s
  footer Generated %date%
  skinparam shadowing false
  skinparam handwritten false
!enddefinelong
title this seems to be needed still
@enddef
 
@startuml
!includedef MACROS
TITLE_ALL("test")
Alice -> Bob : hello2
@enduml  

Also, I guess I will have to update my vim plugin so that it detects the plantuml file type when the first block is startdef.

Thanks,
Christophe
commented Mar 29 by plantuml (134,570 points)
edited Mar 29 by plantuml
> And this works only if the macros are in the same file, correct ?
> (removing the need for the new variables you provided, in that particular case).
Yes, correct.
We will keep the new variables anyway, as it may be still useful for some needs.

About macros, there was an issue in previous beta, we've fixed it in last beta (beta 11), so your example should work now.
(Thanks for your tests by the way!)
https://www.dropbox.com/s/koo42q3d9gxw288/plantuml.jar?dl=0

About vim plugin, no sure if it need some update, as long as it detects @start/@end instead of @startuml/@enduml
commented Mar 29 by Chris38 (390 points)
The last beta works beautifully for me, thank you!
Christophe
...