Save generated diagrams to file

[skuro]

Taking the discussion from #39, which introduced both a way to store the generated diagrams into files and open a browser to view the graphics.

Save to a file

That's a very good addition, it can definitely help out folks and keep the generated diagrams somewhere when needed. But as in your implementation you use custom variables, they become global state which would result in the same file being ovewritten in case more than one PlantUML file is being worked on at the same time. I would rather have the output file being setup on a per-buffer basis, using browser tabs to switch to the generated diagram of interest.
My point is that saving files can be a broader thing than just preview: you could store them into some git tree, your website static/ folder, etc. You need different diagrams to output in different paths.

Manage the browser

It feels to me like taking control over the browser is stretching plantuml-mode responsibilities too far. I can expect users to mostly use web browsers or emacs itself for preview, but I can still see too much variation in people setups to make plantuml-start-external-browser more of a maintenance hell then an added value (thinking here of FF + Chrome + Safari + IE, plus versions).
Once the diagram is saved to a file, people who prefer other apps than emacs have a quick way to open up their favorite viewer. I'd leave plantuml-mode to optimize for emacs preview and leave it to the user to make his/her own workflow with a different app.

[abcdec]

@skuro,

OK, let's discuss.

I positioned this as a "yet another preview functionality", not to generate or manage output files.

I intentionally designed this to use a single temporary file generation to always show latest compile result in a single preview window in an external browser.

This is in line with current preview design, that is, by typing C-cC-c, you instantly sees the result of a current work-in-progress diagram source in a single preview buffer "PLANTUML Preview" without requiring any other typing and switching Emacs buffer editing context, keep it simple approach.

Also this is not to manage the browser, but just starting a browser as part of "preview functionality" like creating the "PLANTUML Preview" preview buffer.

If we had a browser that can take standard input or other IPC method to read source data and shows diagram to the user, no temporary file would be even needed. Creating file and starting a browser is a "preview function" which consists of rendering source and showing the result in a UI on a volatile basis.

A few comments:

My point is that saving files can be a broader thing than just preview: you could store them into some git tree, your website static/ folder, etc. You need different diagrams to output in different paths.

"broader" can mean "more complicated", and it is not necessary to achieve the goal of:

As a text mode Emacs user, a Windows user and a multi-display workstation user, I would like to edit any PlantUML source data in temporary buffers or file buffers in Emacs, taking advantage of nice language support features like keyword coloring, completion, indentation, pretty formatting etc, and check updated diagram on a fixed location in another large screen frequently and instantly, without switching Emacs editing context and without moving fingers away from Emacs.

And, because the goal of the feature is not to save files in various locations, I do not have a good requirements how the multi file management should work. For example:

• where files should be saved
• how files should be named
• how file generation should be triggered
• how region rendering (just added recently) should be handled
• how work flows look like, concrete use cases to better understand any other needing requirements

Yes, it might be a good idea still to support general multiple file generation and management, but that isn't the objective of this particular feature. Also supporting file savings feature could mean extra complexity with no real users. If you have a specific use cases you think plantuml-mode should support and used by some users, please elaborate a bit, we can build a set of requirements based on such concrete use cases. From example you cited above like 'website static/' folder, not sure exact work flow looks like. (I can guess but not sure it will be accurate.)

I can still see too much variation in people setups to make plantuml-start-external-browser more of a maintenance hell then an added value (thinking here of FF + Chrome + Safari + IE, plus versions).

Sure, it might need some more adjustment in the future as this software evolves. 'A maintenance hell' sounds a bit strong though, and maybe too early to say. It can limit the community's possibility for future usability evolution.

I'd leave plantuml-mode to optimize for emacs preview and leave it to the user to make his/her own workflow with a different app.

Why we should limit ourselves to just Emacs? If there is a way to support PlantUML user in various different environment and workflows, as long as Emacs is involved and plantuml-mode can help, there should be nothing wrong to have plantuml-mode support such needs. While Emacs preview should evolve, plantuml-mode can also optimize other means to help various users.

Anyway, let me think about how generic file management part can be added to support what you recommend while still meeting the above mentioned goal.

(Please don't get me wrong - I appreciate your feedback and insight, and understand what you are trying to do and trying to avoid. Let's continue this thread and agree on a solution. Also due to time limitation towards year end, I might be slow in responding to the thread. Please bear with me.)

[skuro]

So, it took me a while before coming back to this, sorry for the delay...

Let me start with my mutual appreciation of the time you spent on plantuml-mode, not only you are an active contributor, but you're really keeping development alive and interesting for me!

Anyway, more on the subject matter: it currently feels to me that the without moving fingers away from Emacs and Why we should limit ourselves to just Emacs? are not really going in the same direction.

The moment we include into the picture an external app, such as a browser, which is started (-> controlled, or at least this is what I would imagine a user to expect) by emacs, you are actually moving away from emacs, at least cognitively if not with your fingers. And in this case I'd rather give users a more direct API with which to integrate, for instance writing to a file at a predictable location so that plantuml-mode doesn't have to do the magic for you. Also, in this way you don't limit yourself to browsers, but any image viewer would also work. As an example, on my mac I'd rather use Preview.app instead of a web browser, which would automagically update the preview upon file change.
In general, I'd stick to the good old Unix phylosophy that everything is a file, making even the temporary file creation a first-class thing that a user can inspect, rather than hiding it behind the plantuml-mode machinery.

As far as use cases for save-to-file go, I can think of a few already, but I'd rather stick to preview with an external app as expressed above.

Now, if we devise a strategy to create the output files with a predictable path, we could then implement the browser-based preview as you suggested, but instead of treating browser as a special case we could think of it just as the app we want to use to preview the result, which should be a command that accepts a path as an argument. This seems to me a more solid strategy to handle this specific kind of workflow.

On the strategy to define the output path for a diagram, and especially considering the preview-region feature, I now think we should be more consistent with the way PlantUML handles it. This means that:

• @startuml my-file directive should be respected
• preview-region might either not be directly supported with the preview-with-app workflow, or based on make-temp-file

What do you think?

[c02y]

Just use M-x save-buffer or C-x C-s to file.svg to save the *PLANTUML Preview* buffer to a svg image file.

If you'd like to preview the plantuml result using png image format by default, put (setq plantuml-output-type "png") in your init.el/.emacs file, note that if you doesn't add the setq line and save-buffer to png file, the file cannot be opened outside Emacs, at least for me.

[ghost]

@c02y M-x save-buffer does not do save the buffer content into file, but a line content consists of <username>@<machinename>.8888 , e.g. [email protected] .

Versions:

• GNU Emacs 25.2.1 (x86_64-w64-mingw32) of 2017-04-25
• plantuml 1.2.5

@skuro Thanks for the plantuml-mode, and some of my opinions:

• The saved file might be better to be the same filename with the output type name in the same dir as the plantuml script, e.g. , e.g. /path/to/xxx.plantuml => `/path/to/xxx.svg'.
• Or if a variable, say 'plantuml-output-dir', has been set, the output file should be placed there with the defined hierarchy (like @startuml some/path/myfile).
  • For example, (setq plantuml-output-dir "/var/www/myhost"), and filename xxx.puml with content @startuml some/path/040seq-crazy, then we should get /var/www/myhost/some/path/puml/040seq-crazy.svg. Or @startuml without a filename, then we should get /var/www/myhost/xxx.svg .

Eagerly waiting for the feature of save to a file 👍

[nedijahij]

Just use M-x save-buffer or C-x C-s to file.svg to save the PLANTUML Preview buffer to a svg image file.

I have tried following this one to save generated image but in mini buffer i got, Text is read only. So, is there a way i can save output to file?

Note: I am using Emacs 27.

[ghost]

@nedijahij try turning the display mode to text by C-c C-c first.

BTW, as a best practice, plantuml-mode is usually used to generate previews in low-resolution, and then the command line of plantuml will be used to generate the final diagrams in high-resolution.

[nedijahij]

@alphatan ah wow it is working! Thank na.

[exot]

Hey everyone,

just for your information, I have been working on this in https://github.com/exot/plantuml-mode/tree/add-file-export (see https://github.com/exot/plantuml-mode/tree/add-file-export-shadow for the version I am actually using right now). Feel free to test!

Best,

  Daniel

[kevin-gwyrdh]

Testing works :-) Thank you

(edit) But after more testing C-c C-c generates the image which previews ok, the image saves from the buffer using C-x C-s (thanks @c02y ) as a png / svg and using the add-file-shadow version from @exot . The saved image can be opened by dired and opened outside of emacs with a variety of apps BUT if inserted into either a .md or .org file within emacs it returns a unknown image error. Other images in same formats work without issue. Very odd.

Thanks all for an interesting journey :-)

[exot]

Hey @kevin-gwyrdh,

thanks for reporting you findings! :) Have you also tried to use plantuml-export (bound to C-c C-e in the add-file-shadow branch) to export images directly to files? This calls plantuml in the background¹ to directly generate the target file and completely circumvents any image processing in Emacs (and thus also works for large diagrams). Maybe those images work in Markdown and Org Mode files?

Best,

  Daniel

Footnotes

1. Only exec-mode jar is currently supported, hope this does not cause too much trouble. ↩

[kevin-gwyrdh]

Hi @exot Thanks that works! Curious