Inline puml #1100

crphang · 2020-03-08T09:38:01Z

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [X] New feature

Resolves #912, continuation of #968.

What is the rationale for this request?

Added inline PUML support which allows user to write PUML inline.

What changes did you make? (Give an overview)

Registered puml as a special tag which allows markdown-it to ignore the content (escaping it accordingly).
Added additional plugin utils that extracts escape content or from source accordingly.
Generates md5 file name when user does not provide it, which allows the file name to be consistent for the same content and prevents regeneration if already exists.

Provide some example code that this change will affect:
The following tag would produce puml documents.

<puml>
@startuml
object Object01
object Object02
object Object03
object Object04
object Object05
object Object06
object Object07
object Object08

object user {
  name = "Dummy"
  id = 123
}

Object01 <|-- Object02
Object03 *-- Object04
Object05 o-- "4" Object06
Object07 .. Object08 : some labels
@enduml

</puml>

Is there anything you'd like reviewers to focus on?
This feature relies on special tags and would require #1099 to be resolved enabling having multiple puml tags:

<puml src="a.png" /> 

<puml> 
...inline puml
</puml>

Switching PUML as a special tag now would break existing behavior. To illustrate this: I have switched all puml tags in tests to:

-<puml src="a.png" />
+<puml src="a.png"></puml>

-<puml src="b.png" />
+<puml src="b.png"></puml>

crphang · 2020-03-23T12:53:01Z

@ang-zeyu could you review this?

This is a much simplified version of previous PR. Tests has worked after I rebased on #1099 🎉.

ang-zeyu

Looks pretty neat 👍, lets wait for some comments

docs/userGuide/puml.md

ang-zeyu · 2020-03-23T13:36:47Z

src/util/pluginUtil.js

+    }
+
+    if (tagAttribs.src !== undefined) {
+      const fileName = fsUtil.removeExtension(tagAttribs.src);


how about adding path.basename(tagAttribs.src)?

I believe we want to have it as fsUtil.removeExtension. For example, if the src='diagrams/activity.puml, this way the output fileName will be src='diagrams/activity.png'.

With path.basename(tagAttribs.src), it becomes activity.png

Hmm I meant fsUtil.removeExtension(path.basename(tagAttribs.src)), but I realised omitting basename keeps the output file in the same directory as the input file.
In that case how about changing fileName -> filePath?

To keep the behaviour when src is specified consistent, if a name is also specified,
should we instead return the file path that is the result of replacing the basename of src with name?

ang-zeyu · 2020-03-23T14:26:10Z

src/util/pluginUtil.js

+  /**
+   * Returns the string content of the plugin.
+   */
+  getPluginContent: ($, element, cwf, config) => {


Could we expand the scope of this PR a little?

I realised cwf will always be available after refactoring componentPreprocessor, let's remove config from the entire plantuml plugin, and consequently the entire config ( I don't see any other plugins using this, but you could double confirm ). This should be a good step for Support always-on plugins #714 (comment) ( which is no longer necessary with the prior refactors ).

We currently don't have any plugins that use config save for this anymore, so let's repurpose it for plugin utils, as calling const pluginUtil = require('../../util/pluginUtil'); on every plugin is dependent on the plugin's location. E.g. if the plugin is in markbind, one would have to know pluginUtil's location relative to the parent module or in the file system.

Let's then expose these pluginUtils. Since we only have one plugin using this now, we can leave it undocumented for a while until we have more and the implementation / requirements becomes more final.

I think its a good step to rectify the solution that was used in #714 (comment), and since pluginUtils as I see it here isn't parser/page dependent, I think exposing it eventually after a few more rounds of plugin development would be a good option. Might be good to have @marvinchin 's opinion since he was involved though 😁.

Hey, could you elaborate more on point 2? Not too sure I am following well

I'm thinking of
preRender: (content, pluginContext, frontMatter, useful safe interfaces (pluginUtil) that we want to expose to plugins) => ...
instead of depending on
preRender: (content, pluginContext, frontMatter, secret unsafe details) => ...
or having to rely on require('../../util/pluginUtil') where the path may differ from plugin to plugin

I see. However, this introduces a breaking change if we remove config from pre/post-render, especially if there are users who have defined their own plugins.

It was intentionally undocumented because it exposed too much implementation details #714 (comment) ( the above comment ); should be fine here

crphang · 2020-03-25T12:48:01Z

@ang-zeyu thanks for your review! Thanks for pointing out that cwf always exist, I refactored slightly to make the code simpler. I also added the changes to user guide.

Currently I would like to scope this PR smaller! Wanted to point out that PlantUML plugin is currently still using config for resultPath and it is quite a common use case. In the direction that you suggested, I believe we could initialize those properties in pluginUtil and expose them as functions within pluginUtil instead.

ang-zeyu

Currently I would like to scope this PR smaller!

Ok with this as well 👍, since the usage from the author's side wouldn't change

I realised the old code also does not deal with the case that src uses {{ baseUrl }}, which is similar to what #1088 fixes for includes. This can be included in a separate PR though, since it'll likely need a supporting interface from pluginUtils.

Couple more nits otherwise:

ang-zeyu · 2020-03-25T15:20:27Z

src/util/pluginUtil.js

+    }
+
+    if (tagAttribs.src !== undefined) {
+      const fileName = fsUtil.removeExtension(tagAttribs.src);


Hmm I meant fsUtil.removeExtension(path.basename(tagAttribs.src)), but I realised omitting basename keeps the output file in the same directory as the input file.
In that case how about changing fileName -> filePath?

src/plugins/default/markbind-plugin-plantuml.js

ang-zeyu · 2020-03-25T15:33:31Z

src/util/pluginUtil.js

+    }
+
+    if (tagAttribs.src !== undefined) {
+      const fileName = fsUtil.removeExtension(tagAttribs.src);


To keep the behaviour when src is specified consistent, if a name is also specified,
should we instead return the file path that is the result of replacing the basename of src with name?

src/plugins/default/markbind-plugin-plantuml.js

crphang · 2020-03-28T08:35:28Z

@ang-zeyu thanks for your review! Indeed filePath would've been more appropriate, updated accordingly. 👍

should we instead return the file path that is the result of replacing the basename of src with name?

I thought a little about this. However, I believe letting name be the source of truth is better considering both inline and referenced puml inputs. For example:

<puml name="output/activity">
activity diagram
</puml>

<puml name="output/object" src="input/object.puml" />

Here, an author would like both output to be in output directory for inline and referenced PUML, instead of having no such option if src is specified.

ang-zeyu

Looks good 👍; works well too
Just one really minor nit left:

src/plugins/default/markbind-plugin-plantuml.js

nbriannl · 2020-03-29T11:08:05Z

Hi, thanks for the changes. Are you able to ping for reviewers in this repo?

crphang · 2020-03-30T05:35:45Z

@marvinchin, could you help to review this? Thanks 🙇‍♂️ !

ang-zeyu

Did another round of testing, looks good! 👍

nbriannl · 2020-04-03T05:32:40Z

Hi Chun Rong @crphang

It seems that updating tests on Windows npm run updatetestwin produces a different set of expected results.

* 'master' of https://github.com/MarkBind/markbind: (41 commits) Document adding new site content in DG (MarkBind#1153) Add relative date feature (MarkBind#908) Use <br> to separate lines of code block (MarkBind#1176) Parse popovers for footnotes (MarkBind#1155) Resolve comments Expand test extensions and fix whitespace checks (MarkBind#1156) Address comments Upgrade js-beautify and provide option to turn it off (MarkBind#1116) Normalize inline puml line ending before hashing (MarkBind#1174) Update tests (MarkBind#1178) Remove fixed bugs from test\functional\test_site\bugs\index.md` (MarkBind#1148) Fix bug in Search for UG and DG (MarkBind#1147) Add inline puml support (MarkBind#1100) Fix hrefs for headings with angular brackets (MarkBind#1089) Update tests for 2.13.1 (MarkBind#1169) 2.13.1 Update vue-strap version to v2.0.1-markbind.39 Fix fontawsome icons don't show underlines to indicate modal/tooltip (MarkBind#1133) 2.13.0 Update test files ...

damithc · 2020-04-18T14:28:49Z

Seems to be working in production. Good work @crphang and reviewers.

crphang mentioned this pull request Mar 8, 2020

Special Tags have parsing issues when closed with <tag /> instead of <tag></tag> #1099

Closed

crphang changed the title ~~Inline puml new~~ WIP: Inline puml new Mar 8, 2020

crphang force-pushed the inline-puml-new branch from aa7eb37 to 05ce1a2 Compare March 23, 2020 12:46

crphang changed the title ~~WIP: Inline puml new~~ Inline puml Mar 23, 2020

ang-zeyu reviewed Mar 23, 2020

View reviewed changes

crphang force-pushed the inline-puml-new branch from 05ce1a2 to aac7d2b Compare March 25, 2020 12:11

ang-zeyu reviewed Mar 25, 2020

View reviewed changes

crphang force-pushed the inline-puml-new branch from aac7d2b to 65177a5 Compare March 28, 2020 08:27

ang-zeyu approved these changes Mar 28, 2020

View reviewed changes

src/plugins/default/markbind-plugin-plantuml.js Outdated Show resolved Hide resolved

Add inline puml support

6f13ed6

crphang force-pushed the inline-puml-new branch from 65177a5 to 6f13ed6 Compare March 29, 2020 10:00

yash-chowdhary added the pr.NewFeature 🆕 Enable users (authors/readers) to do something new label Apr 1, 2020

ang-zeyu approved these changes Apr 1, 2020

View reviewed changes

ang-zeyu added this to the v2.13.2 milestone Apr 1, 2020

ang-zeyu merged commit ab059ec into MarkBind:master Apr 1, 2020

ang-zeyu mentioned this pull request Apr 1, 2020

Add plugin local asset collection #1129

Merged

marvinchin pushed a commit that referenced this pull request Apr 10, 2020

Add inline puml support (#1100)

0e65c9d

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Inline puml #1100

Inline puml #1100

crphang commented Mar 8, 2020

crphang commented Mar 23, 2020

ang-zeyu left a comment

ang-zeyu Mar 23, 2020

crphang Mar 25, 2020

ang-zeyu Mar 25, 2020

ang-zeyu Mar 25, 2020

ang-zeyu Mar 23, 2020

crphang Mar 23, 2020

ang-zeyu Mar 23, 2020

crphang Mar 23, 2020

ang-zeyu Mar 23, 2020

crphang commented Mar 25, 2020

ang-zeyu left a comment

ang-zeyu Mar 25, 2020

ang-zeyu Mar 25, 2020

crphang commented Mar 28, 2020

ang-zeyu left a comment

nbriannl commented Mar 29, 2020

crphang commented Mar 30, 2020

ang-zeyu left a comment

nbriannl commented Apr 3, 2020

damithc commented Apr 18, 2020

Inline puml #1100

Inline puml #1100

Conversation

crphang commented Mar 8, 2020

crphang commented Mar 23, 2020

ang-zeyu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

crphang commented Mar 25, 2020

ang-zeyu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

crphang commented Mar 28, 2020

ang-zeyu left a comment

Choose a reason for hiding this comment

nbriannl commented Mar 29, 2020

crphang commented Mar 30, 2020

ang-zeyu left a comment

Choose a reason for hiding this comment

nbriannl commented Apr 3, 2020

damithc commented Apr 18, 2020