Feature Request: Markdown Support (for documentation)

Questions & Suggestions
1

When documenting a macro, I love the fact we have the Comments action. And I also love the fact that we can sneak in some Rich Text using something like a disabled “Display Text in a Window” action (and if there’s another way, please let me know).

But what I’d really love, is to have a Comment-type cell that supports Markdown. That would be awesome.

I’d also like to request that Comment actions, either as they exist now, or with Markdown support, would not limit their height. I know we can scroll, but there are times when I’d like to not have to do that, so people don’t miss something.

Also, scrolling with the mouse is problematic. Sometimes it scrolls the contents of the Comment action, sometimes it scrolls all the actions, and sometimes it does both. Have Comments that don’t limit their height would help with that.

I won’t hold my breath for any of this, but it’d make a good feature for version 8.0, right? :smile:

3 Likes
2

I’ve been wanting styled text in comments for some time now.

Especially so I can use a monospaced font.  :sunglasses:

-Chris

1 Like
3

Agreed. I could make good use of this.

4

I don’t understand how markdown would be superior to rich text in this case.

Rich text case for the comment is on the todo list.

3 Likes
5

It's not, actually.

Well, then, cool! Thanks!

6

There's a potential issue with both RTF and Markdown, and it has to do with embedded images, and how they're encoded in macros.

I created some RTF documentation, which on disk takes up 116 KB. I pasted it into a "Display Text" action, and it looked pretty good. But when I exported the macro, it was almost 6 MB.

I really don't know if this is a concern at all, or only a minor concern, or what. And chances are you've already thought of this. But just in case, I wanted to give you another reason to keep this low on the priorities list. I thought I'd let you know.

7

LOL, this sounds exactly like the old MS-Word problem where it duplicates image data in uncompressed form when you save as RTF. You don’t have Word involved in your RTF workflow somehow?

8

No, this is all KM, and how it saves the RTF data.

9

Feel free to send me the offending RTF document so I can look.

But internally, Keyboard Maestro stores styled text in NSAttributedStrings, and they are written out as RTF or RTFD format - I am not sure I have any control over the the process.

10

I am good with either, whichever can be provided quickest.
I do have a small preference for rich text, since I use Evernote a lot to compose and store info, and if KM used rich text that would make it very easy to copy/paste between KM and Evernote.

11

I can confirm the problem with the file size bloat, when images are involved.

I made a little reasearch, and unfortunately this lead me into the history of RTF:

Until RTF version 1.5 it was not possible to embed image formats like PNG, JPG. However it was possible to embedd image data. From the RTF 1.0 specs:

An RTF file can include picture files created with other applications.
These files are in hexadecimal (the default) or binary format.

On Windows the image data was embedded as WMF, on the Mac as MACPICT. These are uncompressed or weakly compressed (RLE) meta formats, suitable for bitmap and vector graphics. You can still verify this today when you open the RTF markup of an image-containing RTF created with MS-Word:

(Besides the image as PNG/JPG (since RTF 1.5) MS Word is still today embedding copies of the images as MACPICT (or as WMF on Windows). That’s the reason why an MS-Word-RTF with an image has 10 times the size of the original image, in case you were ever wondering.)

RTF version 1.5 introduced the possibility to embed images in their proper format (PNG, JPG). However Apple decided to not follow this path. Instead Apple invented the RTFD format. RTFD is just a folder (“bundle”) that contains the RTF file (styled text) and any images as separate files.

In other words, instead of embedding images, Apple is attaching them. And still today the only “legal” way on a Mac to produce RTF with images is as RTFD bundle.

Back to KM:

Since KM macros are not stored (nor exported) in a bundle but in a simple XML file, it’s hardly imaginable to use RTFD (i.e. a file wrapper) here. What likely happens here, is that the RTF(D) data —including any image data— is just output to the “styled text” data stream, uncompressed. (See this.) The result is imilar to image-containing RTFs before version 1.5.

To my knowledge, the only way on the Mac to write RTF files to disk with embedded JPGs or PNGs is with third-party apps like MS Word or Nisus Writer. And you’ll notice that these images will not be visible when you open the RTF file with Textedit. These apps are most certainly not using any of Apple’s frameworks for this.

So I heavily doubt there will be any easy solution for KM. Except that the macro format will change to a bundle format. This should make it possible to attach images in their original, compressed format, i.e. styled text and images in an RTFD wrapper.

FWIW.

Maybe I’m completely wrong, but then you have at least learned a bit about the history of RTF :wink:

1 Like
12

Peter already confirmed to me privately that it was unlikely he was going to be able to fix this.

Thanks.

13

I hope you’ve read my writeup nevertheless :wink:

14

Unfortunately, I’ve already been down that road. A while back, I learned way more than I ever wanted to know about the RTF format. shudder

3 Likes
15

I am interested in having either Markdown or Rich Text support mostly to have better formatting of my comments. Rarely would I need to embed an image.

But even with just rich text (and no images), a KM Display Text action requires about 12X as much storage for rich text than plain text:

The same rich text saved in a TextEdit file is 1/3 smaller than the exported KM Action.

Here is the KM Display Text with Rich Text:

This requires only about 6KB, which is still very small, IMO.

####Here's what I really like about the RTF in the Display Text:

  • Handles the display of tables properly
  • Handles the display of bullets properly (including auto-indent)
  • Handled a paste from Evernote without any issues

So, I may convert my Comment template for macro header to a Display Text with Rich Text, and see how it works.

16

@peternlewis - If we start putting our attribution comments in disabled Display Text in a Window actions, what kind of impact might there be to KME’s speed or memory consumption, because some macros would potentially be exponentially larger than they are now?

My initial thought is that it would be negligible, but of course you’d know better than I would. What do you think?

1 Like
17

This is because of RTF. RTF adds a lot of markup.

This is plain text:

Hello!

This is the same as RTF (as produced by Textedit):

{\rtf1\ansi\ansicpg1252\cocoartf1404\cocoasubrtf470
{\fonttbl\f0\fnil\fcharset0 HelveticaNeue;}
{\colortbl;\red255\green255\blue255;}
\paperw11900\paperh16840\margl1440\margr1440\vieww13060\viewh9600\viewkind0
\pard\tx566\tx1133\tx1700\tx2267\tx2834\tx3401\tx3968\tx4535\tx5102\tx5669\tx6236\tx6803\pardirnatural\partightenfactor0

\f0\fs28 \cf0 Hello!}

‌In this example it is far more than 12×. But the relation changes in favor of RTF when you have more text.
‌

The additional ~30% come from the base64 encoding of the “Styled Text” data in the KM action. Copy the RTF markup from above and send it through a base64 encoder to see it grow.

I guess the base64 encoding is required by the XML format. Not sure though.

18

The only issue is the size of the Keyboard Maestro Macros.plist file, which is saved/loaded monolithically for all changes.

So it is the same issue as having thousands of text expansion macros. See:

1 Like
19

Peter, you've done an outstanding job of designing and implementing Keyboard Maestro, and I certainly would not even think of suggesting design changes.

I'm just curious, for potential use elsewhere, if you ever considered other storage methods, like a SQL database, for storing the complete macro definition?

20

Hey JM,

He has.

This came up in our discussions of hacking around with Keyboard Maestro .plist files. Peter said he won't guarantee any of those methods will work for any length of time due to possible changes in Keyboard Maestro's architecture.

It seems likely that at some point he'll move to a database-driven design, but that will be a whole lot of work.

-Chris

1 Like