In an attempt to improve PlantUML documentation...
Wiki Toc Recent changes View page history Add new chapter Reorder page Raw
![]() |
![]() |
|
Initial requestA user has requested a supported or suggested method of using citations within a flow diagram. The goal of this page is to think together on an approriate solution. |
|
FunctionalitiesWhat is it that is needed? You can start by voting:
Citation outputWhat is wanted is effectively the ability to produce this:
It is likely jounral editors may insist on slight variations like these:
Ideally where the graphic format allows it, the citation should produce a clickable link which may take you to the Reference section of a document
Reference List outputIf plantUML is hosting its own reference list in the figure, then it will need the ability to format up the reference correctly (or would it just be passed a preformatted string? But the preformatted string would need bold, underline and italics in the string? Normal reference lists are on fresh lines and look like this 1. Derwing, T. M., Rossiter, M. J., & Munro, M. J. (2002). Teaching native speakers to listen to foreign-accented speech. Journal of Multilingual and Multicultural Development, 23(4), 245-259. 2. Thomas, H. K. (2004). Training strategies for improving listeners' comprehension of foreign-accented speech (Doctoral dissertation). University of Colorado, Boulder. Space is at a premium in figures, so it may be sensible to pick a default reference style that minimises space, but also to consider NOT using new lines per reference. 1. Derwing, TM et al (2002). Teaching native speakers to listen to foreign-accented speech. Journal of Multilingual and Multicultural Development, 23, 245-59. 2. Thomas, HK (2004). Training strategies for improving listeners' comprehension of foreign-accented speech (Doctoral dissertation). University of Colorado, Boulder. And so the functionality would produce something like this:
InputsApart from the basic syntax of how to reference, there would be a need to provide styling information to the outputs. While plantUML should make some good default choices, it is likely picky journal editors may have some specifics they want to specify. Therefore it would make sense for plantUML to either be able to take references to 2 files (URLs perhaps) that would save the overall content being in the UML?
|
|
Proposal 1 for syntaxThis proposal 1 is the following one.
Advantage ?The[@anderson2015] format is used in some flavours of markdown. It remains human readable. An alternative might be latex's format of \cite{anderson2015} .
DrawbackI've had a breif play in latex to see what can be done.Not sure syntax is the place to start! Sorry - functionality is the place to start! What is it that is needed? Citations to a reference box within in the diagram? Or citation to references held elsewhere in the host document?Ok, we have added a new chapter Functionalities. This chapter will be moved before this one when the wiki will allow us to do so :-)
However, the box widths are wrong because it thinks the box has \citep{anderson2015} in it and it actually has (1).Works in so far as after manipulating the \ latex can make it a reference like (1) or ^1 etc, and Latex will then paste in the references at the end of the document along with any from the text part of the document. This feels clean. Latex will also make the citation a hyperlink to take you to that reference. This puts the effort of referencing and formatting etc with latex which has the abilities. Otherwise you start having to do a lot of work!Well, this syntax is too close to Latex (PlantUML Team opinion). Note that whatever the syntax we use (for example if you were limitting this to latex - you don't need the @Manual{} section above at all... (thats in the latex effectively) Couple of bits of sample code:Latex wont suit everyone! But can't see how you would be more functional easily in a PNG for instance.We really don't want to focus on LaTex only. It's important for us (PlantUML Team) to have something that works for all formats (including PNG). For PNG, we could list references details at the bottom of the diagram, for example.
Reference box on the diagramFor simpler diagrams I can see a use for a reference box on the diagram. Effectively a notes box with the references in it. BUT - unless there is code ready to lift from other projects this is a LOT of effort - you'd need to format the citation (i.e. do you want a superscript, a normal number, round or square brackets, what about when you reference [1 - 4] and what about (1,3,4) or (1, 3 & 4) etc. Then the formatting of the actual reference changes by place of publication too. There are 'standard' formats for sharing those formats etc but perhaps the use case is not huge.Rather that using notes box, I wonder if listing references on the bottom of the diagrams is a better solution. |