search

oxygenxml / dita-ot-diagrams-plugin

Dynamically convert PlantUML content inside DITA topics to SVG
Apache License 2.0
9 stars 3 forks source link

Clarification Needed in README.md on Plugin Inclusion and Installation Process #9

Closed SmartLayer closed 1 year ago

SmartLayer commented 1 year ago

I am filing this issue to request some clarifications and improvements in the project's README.md. Here are the points that need to be addressed:

  1. Plugin Inclusion in OxygenXML: The project's name (com.oxygenxml) suggests that it is part of OxygenXML. I have purchased the editor version 25.0 (not 25.1) but could not find this plugin included in the software. It would be helpful if the README could clarify whether this plugin is in any version of the Oxygen XML Editor or is planned to be included

  2. Plugin Installation Process: The project name (dita-ot-diagrams-plugin) suggests that it should be installed as a DITA-OT plugin. However, it is not immediately clear whether "dita-ot" in this context refers to a DITA-OT component inside OxygenXML or the open-source project DITA-OT. Guessing it's the latter, when I tried to install the plugin using the dita install command, I received an error message indicating that the plugin could not be found in any configured registry. If manual installation is required, this should be clearly stated in the README to save users time and avoid confusion.

Here is the error message I received:

$ dita install com.oxygenxml.diagrams.svg
Error: Unable to find plugin com.oxygenxml.diagrams.svg in any configured registry.

I believe addressing these points in the documentation would greatly improve the user experience and make the plugin reach a lot more people.

raducoravu commented 1 year ago

@weiwu-zhang thank you for the feedback. This free open source project is under the "oxygenxml" organization, so I consider that it can use the "com.oxygenxml" plugin folder name. Not all open source plugins that we build and maintain are part of the publishing engine bundled with Oxygen XMLEditor/Author. I just updated the Readme to state this more clearly and to give more details about the installation of the plugin.

As a side note, would you consider it useful if this plugin would be pre-installed with the publishing engine bundled with Oxygen XML Editor/Author?

SmartLayer commented 1 year ago

I really appreciate that you updated README. As an Oxygen XML Editor user, I find it useful if it can handle diagrams in mermaid/plant UML. There are things I can't do in dita-ot conveniently, such as generating CSS-based PDF files (the default PDF output trans type in dita-ot is optimised for books rather than booklets, so I use Oxygen's CSS-based PDF transformation often).

raducoravu commented 1 year ago

@weiwu-zhang thanks for the kind words. The CSS-based publishing can be done freely if using Oxygen's bundled DITA Open Toolkit. If you want to do it from a command line you would need to use our commercial Oxygen Publishing Engine licensing: https://www.oxygenxml.com/publishing_engine.html