Freron MailMate

Comments and changes to this ticket

• 

  benny September 5th, 2022 @ 01:02 PM

  • State changed from “new” to “accepted”

  Seems like it could be a nice feature. The hard work is figuring out how to make it available to MailMate via, e.g., a bundle (like the math bundles) or a standalone javascript used directly by MailMate. Let me know if you (or anyone else) has thoughts on that.

  (No promises.)

• You flagged this item as spam.
  

  Stefan Doehla September 7th, 2022 @ 08:40 AM

  • Tag cleared.

  In other programs or web applications, the syntax for mermaid is usually:

  ```mermaid
  flowchart LR
      A --> B
  

  which gives a very simple diagram.

  The one option is mermaid-cli. This has to me the advantage that MM would not be cluttered and one could easily update mermaid independently. Also static images are created that could be embedded in a mail. Could probably be put into a bundle - but I am not familiar with your extension scheme when this could be triggered etc so that the preview is updated automatically or images are added to outgoing mails etc. More info here: https://github.com/mermaid-js/mermaid-cli

  The usual way of integrating it though seems to be via the JavaScript API. My skills here are rusty, but this seems to defer the rendering to the HTML viewer. No problem locally I'd assume, but not sure it works for perople using other mail clients and whether those allow rendering via JS. Also seems to be a bit less secure when an external resource needs to be queried for the full Mermaid package to render (and it's not part of every outgoing mail). See: https://mermaid-js.github.io/mermaid/#/./usage

• You flagged this item as spam.
  

  Stefan Doehla September 7th, 2022 @ 08:50 AM

  Maybe to add: brew failed to install mermaid-cli for me - but npm worked.

  npm install @mermaid-js/mermaid-cli
  

  I fear it's hard to integrate mermaid-cli (the mmdc tool) into MM directly, given the node.js dependency. But as I understand bundles, they could refer to an existing installation, so one could install mermaid-cli/mmdc manually - plus the bundle and it would only need to find mmdc? I have the impression that puts least burden on MM.

• 

  benny September 7th, 2022 @ 08:59 AM

  It would be a “quick” solution to ask the user to install mermaid-cli, but maybe that would be fine (at least at first) since it's an expert feature. Too bad if homebrew doesn't work (I prefer that).

  With respect to outgoing emails I think mermaid-cli should be asked to output SVG which is then directly embedded in the HTML generated. This is a vector format and it'll look great. It'll apparently work for most recipients except Gmail (webmail) users: https://www.caniemail.com/features/image-svg/

  An alternative is PNG output, but that makes it more complex for MailMate to handle and it'll look worse.

  It is, by the way, interesting that there's a clash between syntax highlighting and conversion. The same is true for the current math-bundles in MailMate. It appears it has the same syntax:

  ```mermaid
  

  (Currently MailMate does not support syntax highlighting for mermaid. I'm just mentioning it in order to not forget this potential issue.)

• 

  benny September 16th, 2022 @ 01:11 PM

  • State changed from “accepted” to “fixcommitted”

  Hold down ⌥ when clicking “Check Now” in the Software Update preferences pane to get the latest test release.

  Then try this:

  ```diagram
  graph
      A --> B
      B --> C
  ```
  

  I decided to use diagram instead of mermaid, but I'm a bit unsure what's best. It might actually be better with mermaid if there are no other (and never will be) utilities converting the same syntax to a diagram. Maybe just make both work (next update). Similar to how MailMate supports both math and asciimath/texmath (the former using the user default).

  Another problem is that one might want to use the syntax highlighter instead of the conversion if wanting to highlight mermaid code. I've decided to solve that by allowing language-mermaid to be used to trigger syntax highlighting instead (next update).

  (The changes needed for this also meant I cleaned up code handling javascript based extensions. This should also allow me to eventually improve syntax highlighting and possibly also the math modes.)

  I'll “close” the ticket, but we can still discuss details/bugs in this ticket.

• You flagged this item as spam.
  

  Stefan Doehla September 19th, 2022 @ 07:23 AM

  Awesome you've added this so swiftly. Was using FSNotes quite a lot last week, and did lots of diagrams, now I can (could, see below) use MM and sed it out right away. As a side note, Gitlab has some rendering issues with Mermaid, especially with "milestones" in Gantt charts. Maybe they have an issue there with CSS and their own usage of the term milestone.

  Still, I have an issue calling it, i.e. no output yet. Can you give a bit more details how you did it now? Are you using the mmdc tool (mermaid-cli) or the minimized JS? In my case mmdc is in /opt/homebrew/bin and running MM just from command line (hoping the PATH variable then get's used by MM) didn't help.

  Otherwise, just looking at the Changelog, the decision should be in any case to accept ```mermaid (and maybe diagram in addition) as this would also allow copying the Markdown formatted text to other tools (like Github, Gitlab, FSNotes, etc.), i.e. allowing re-usage of already formatted text.

• 

  benny September 19th, 2022 @ 07:30 AM

  The r5917 release should also accept mermaid.

  There's a “bug” where you have to enable Pygments in the Composer preferences pane (and install it in the Bundles preferences pane). There's no separate setting yet to just enable Mermaid.

  It's based on a bit of local javascript and the server-side version of the minimized javascript. Nothing should be needed to be installed.

  If the above doesn't help, do you get any error messages or is it just working as if nothing is done with the input?

  (I've made it such that if parsing fails then the parse error output should be shown instead of the code.)

• You flagged this item as spam.
  

  Stefan Doehla September 19th, 2022 @ 08:29 AM

  Thanks. That already does something. I get now an error saying:

  Bundle command failed (event: generate_diagram)
  Explanation: Unable to reach output format type (discard != html)
  

  Closing the draft and re-opening it just showed the source code for the graph, I then disabled and enabled Pygments again, then also the error reappeared.

  Getting there ;)

• 

  benny September 19th, 2022 @ 10:12 AM

  Hmm, this might be an update related issue. Seems MailMate cannot find the new bundle command. Could you try issuing this command:

  touch /Applications/MailMate.app/Contents/SharedSupport/Bundles/MailMate.mmbundle/Filters/Mermaid.mmFilter
  

  Then see if it changes the error output.

  (With regards to 'gantt' charts, MailMate also had some issues since these work a bit differently with sizing.)

  Also, I should mention that MailMate generates and embeds SVG. This won't work well in all receiving email clients, in particular webmail (including Gmail). Some clients will likely work a bit better if the SVG is in a separate attached file (but MailMate cannot easily do that internally) and most will work if is then also converted to PNG, but this has the additional problem of losing the scalability provided by the vector-drawing. Ideally, there would be options to do this.

• You flagged this item as spam.
  

  Stefan Doehla September 19th, 2022 @ 10:45 AM

  Thanks! That did the trick! Really awesome.
  Also things like setting the theme work.

  ```mermaid
  %%{init: {'theme': 'forest' } }%%
  graph LR
      A --> B
      B --> C
      C --> A
  

  SVG is not an issue for me, but I see that it may not be that common as one would like SVG to be.

  Now comes the testing phase :)

• You flagged this item as spam.
  

  Stefan Doehla September 21st, 2022 @ 11:29 AM

  Some further update: It still works :)

  One issue that now pops up though is that python3 seems to ge triggered somehow (maybe because I had to activate Pygments). It constantly wants to install the command line developer tools, which I already have installed at least once. I can click this away, but it's somewhat annoying.

  This is the error in MM:

  Bundle command failed (event: generate_diagram)
  Error Output Error: Parse error on line 2:

  ^ Expecting 'NEWLINE', 'SPACE', 'GRAPH', got 'EOF'
  Status Cache

• 

  benny September 21st, 2022 @ 03:23 PM

  That error message is from mermaid. (Also, I think MailMate should probably hide the “detail” shown above the headers until trying to send the message. It's a bit too chatty while “coding” a diagram.)

  The next update will require you to explicitly enable Mermaid (with a hidden preference), but then you don't need to enable Pygments.

  I also think I have a replacement for Pygments on my todo list which would not require Python. That could potentially be the default instead (in order to allow users to avoid the Command Line Tools). But I'm not sure when I'll have time for this.

• 

  benny September 22nd, 2022 @ 07:40 AM

  Just to be clear, Mermaid needs to be enabled like this (in r5918+):

  defaults write com.freron.MailMate MmBundleCommandForDiagramGeneration -string "BCA016BB-96DF-4EBB-8DD6-4BE467FCA194"
  

  Also, the Mermaid bundle relies on server-side javascript files, but allowing this was a potential security risk. Therefore, I've now made sure MailMate completely blocks external resources when running javascript except if it's within this folder: https://cdn.jsdelivr.net/npm/mermaid/dist/. That'll work for now, but it'll also block any other bundles from doing something similar. I'll likely need to add some general method to allow other bundles to access similar server side files.