Incremental parsing of PlantUML markup?

Question

I've just started using PlantUML properly and I'm really enjoying it. Much better for reference and keeping in source control than flat .svg or .dia files.

Maybe this is crazy, but what I'd really like is to be able to do is intersperse sections of PlantUML markup amongst sections of other textual markup. Here's my use-case:

We're a Perl shop, so all our internal documentation is written in Plain Old Documentation (POD) format. POD commands declare blocks of content. Different parsers exist to convert POD to different formats: man, HTML, etc.

I want to be able to intersperse pieces of my PlantUML markup between POD sections which would describe them textually. I know you can add notes on diagrams, but maybe I'm too verbose for that :) Furthermore, POD can be used in source files, and I feel it would be good to keep both documentation and diagramming near to the code to which it refers.

So you'd have something like this (POD declarations are in the form '=command'):

=head1 Method name

Paragraph of text, blah blah blah.

=plantuml

@startuml img/my_diagram.png

...

@enduml

=end

=end

sub foo {

...perl code here...

}

=head1 Another method name

Blah blah, I talk a lot...

=plantuml

@startuml img/my_diagram.png

...

@enduml

=end

=end

sub bar {

...more perl code...

}

...

The thing that seems to prevent this at the minute is that if PlantUML finds two @startuml declarations referring to the same output file (img/my_diagram.png above), the last one will always overwrite those before it.

Yes, I could make each section refer to a different output file, but that would probably increase repetition, when what I really want is to be able to run the same file as Perl code, view it as POD with perldoc, or run it through plantuml to get a diagrammatic representation of the whole file.

I imagine that other text-based documentation systems like phpdoc could benefit from the same ability!

Even if this wouldn't be your top priority as a feature, I'd be interested to know whether you'd be in favour of it in principle :)
 

Answer 1

No, it's not crazy. That's exactly what PlantUML has been designed for. Integration with POD is indeed a great idea! I hope that you will make it works, and if you write a how-to document, I will add a link to that document.

The thing that seems to prevent this at the minute is that if PlantUML finds two @startuml declarations referring to the same output file (img/my_diagram.png above), the last one will always overwrite those before it.

What you can do, is to use @startuml tag without giving filename (see http://plantuml.sourceforge.net/sources.html). In that case, there is an automatic increment number added to the generated file name.

More over, you can use =@startuml notation in your POD, because PlantUML also recognize non letters character before the @startuml tag:

=head1 Method name
Paragraph of text, blah blah blah.
=@startuml
...
=@startuml
=end
sub foo {
...perl code here...
}
=head1 Another method name
Blah blah, I talk a lot...
=@startuml
...
=@startuml
=end
sub bar {
...more perl code...
}

Note also that you can use another feature of PlantUML : it seems to me that you can put comment using a # inside POD.

This means that you can use this:

=head1 Method name
Paragraph of text, blah blah blah.
# @startuml
# Alice-> Bob
# @startuml
=end
sub foo {
...perl code here...
}
=head1 Another method name
Blah blah, I talk a lot...
# @startuml
# ...
# @startuml
=end
sub bar {
...more perl code...
}

This text can be parsed by POD (because # line will be ignored), and parsed by PlantUML (using command line/ant task because PlantUML will recognize @startuml, even if they are in # line). You have to add a link toward images generated somewhere in the POD source.

One drawback of using @startuml without filename is that, since file are automatically numbered, when you update your documentation and insert an new diagram, you may have to update all links toward the other images (because the numbering may change).

So I am thinking about allowing to use special tag when defining filename. For example:

@startuml {filename}_init.png

Where {filename} will be replaced by plantuml by the filename of the file containing the diagram (without the extension). So if this line is in file called foo1.perl, then the generated image will be foo1_init.png.

What do you think about that ? Keep us informed of your work.

Comments

Thanks for your quick and comprehensive reply!

Taught me some cool tricks - I didn't know about the parameterised file naming, or the autoincrementing name.

Is there a way though, instead of autoincrementing the filename to create a separate file, of having successive @startuml ... @enduml sections *append* to previous ones, to build up into one big diagram?

If I might suggest a syntax, how about

@startuml +

... to append to the immediately previous opened and closed @startuml ... @enduml section, and/or

@startuml +my_other_file_name.png

... to append to a named one?

I imagine the problem would be that the code currently finishes its handling of UML sections as soon as it sees @enduml, then "forgets", so there's nothing to refer back to.

Possibly some pre-processing of the whole file could be done, looking for "@startuml +" sections and concatenating them together, in a tempfile even, then processing them as normal?

---

Sorry, I don't understand your suggestion. You want to have
@startuml
class foo1
@enduml
...
@startuml +
Bob->Alice:hello
@enduml
...
How could those two different sections generate only one single PNG file ? Are you expecting this to be interpreted as:
@startuml
class foo1
Bob->Alice:hello
@enduml
Thanks for explaining!

---

Yes, more or less. Obviously it would be subject to all the same logic as usual, so the combined sections would have to make sense when put together. But yes, that's what I meant.

It would just mean that you could keep relevant pieces of UML documentation near relevant code, but then have a bigger, comprehensive diagram when you process the whole file.

Would that be impossible, for the reasons I guessed above?

---

... or perhaps just undesirable? :-)