Does not properly preview tables from GitHub READMEs

Stuart Hertzog's Avatar

Stuart Hertzog

20 Sep, 2017 08:03 PM

MMC 4.0.2(56) doesn't preview some tables in GitHub README files, example file and screenshot provided.

iMac 7,1 OS X 10.11.6

  1. Support Staff 1 Posted by Fletcher on 20 Sep, 2017 09:45 PM

    Fletcher's Avatar

    Stuart,

    Add a `|` to the end of the table separator line:

    name | default | description
    ----- |---------|------------|

    I'll look at MMD-6 and see why that is required.

    F-

  2. Support Staff 2 Posted by Fletcher on 20 Sep, 2017 10:02 PM

    Fletcher's Avatar

    Hmmm... More interesting to me -- when I paste your text in, none is processed by the syntax highlighter, until I edit small parts.

    Found the edge case that was being triggered, so that will be fixed for 4.0.3

    So two birds (bugs?) with one stone!

    F-

  3. 3 Posted by Stuart Hertzog on 20 Sep, 2017 10:09 PM

    Stuart Hertzog's Avatar

    I also noticed the lack of syntax highighting, but it didn't reappear
    after editing, although ssome files highlighted properly.

    Adding | to the end of the table separator line did nothing for the
    Preview, nor adding | to the end of each row, but that table has always
    displayed properly in Marked2 no matter what mods I put in.

  4. Support Staff 4 Posted by Fletcher on 20 Sep, 2017 10:20 PM

    Fletcher's Avatar

    Are you sure about the separator? I just checked again, being sure to
    use 4.0.1 and 4.0.2 from the App Store, not a development build.

    Typing the single character '|' at the end of the second line:

    name | default | description
    ----- |---------|------------|

    Fixes it.

    Are you sure you don't have Markdown compatibility mode turned on?
    Markdown doesn't have tables.

    See attached images

    F-

  5. 5 Posted by Stuart Hertzog on 20 Sep, 2017 10:33 PM

    Stuart Hertzog's Avatar

    Oh! Duh! Turning off MD compatibility fixes the syntax highlighting and
    table display issues (with your mod) Apolgies!

  6. Support Staff 6 Posted by Fletcher on 20 Sep, 2017 10:40 PM

    Fletcher's Avatar

    I'm asking in all seriousness, because you're not the only one doing this. Not even the only one today.

    Why does everyone keep turning on the Markdown compatibility mode and then act surprised when things that aren't Markdown don't work?

    ;)

    Do I need to put a "Are you really sure you want to push this button?" warning???

    :)

    Fletcher

    PS> I am serious -- I don't want to take that option away (some people do want "pure" Markdown, but I suspect a vanishingly small percentage of users even know what that means). But I also wonder if it causes more harm than good. Input welcome!

  7. 7 Posted by Stuart Hertzog on 20 Sep, 2017 10:47 PM

    Stuart Hertzog's Avatar

    I was already thinking about this as I do know the difference between MD
    and MMD.

    The problem is that the switch is buried in the Preferences, and there
    is no indication that MMC is in MD or MMD mode. Would that be possible
    to program into the display somewhere?

    Another way is to have this toggled automatically if the file extension
    is .md or .mmd and alert users to this.

    Stuart

  8. Support Staff 8 Posted by Fletcher on 20 Sep, 2017 10:58 PM

    Fletcher's Avatar

    * File extensions are not reliable (I use .md and almost never use .mmd,
    but as you can imagine almost always use MMD features). There's enough
    trouble with file extensions and UTI's that I am not going to make that
    any worse... ;)

    * This used to be available as a toggle menu item but:
    1. This seemed to unnecessarily clutter the menu bar as I suspect it is
    almost never used

    2. Which requires tracking on a per window basis which adds additional
    complexity with (seemingly) little benefit.

    Do you turn it on and off for different files? If so, why (again, I'm
    asking not challenging)? There's nothing that can be done in regular
    Markdown but not in MMD, except for a couple of very slight differences
    (that I can think of). For example:

    * `#Header` (with no space) is valid in Markdown, but not in MMD (and
    not in commonmark and a few others). In this case, I suspect most users
    are going to learn quickly to use the space at all times.

    * Compatibility mode turns off a few preferences, such as anchors in
    headers, footnotes, etc. However, these can be turned off individually
    in the preferences without the side effect of killing every other MMD
    feature that you are using.

    I was trying to "hide" the setting in the prefs to keep it out of the
    way, except for those who really need it.

    Fletcher

  9. 9 Posted by Stuart Hertzog on 21 Sep, 2017 12:56 AM

    Stuart Hertzog's Avatar

    As MMD is the default (after all, it's called MultiMarkdown Composer!)
    perhaps some alert (small red box upper right of editor?) when MD mode
    is switched on? Or, the alert could display when a table is encountered
    in MD mode? As it makes a difference as to whether or not tables are
    displayed, something like that is needed, IMHO. Users are busy thinking
    about other things.

    Stuart

  10. Support Staff 10 Posted by Fletcher on 21 Sep, 2017 01:00 AM

    Fletcher's Avatar

    But why did you turn it on? Playing around with preferences and forgot
    about it? Or needed it on purposefully for one document, and then
    forgot when you switched to a new document? Needed to verify that your
    document would work on a different system somewhere?

    Trying to understand the reasoning behind the behavior so I can provide
    the right solution.

    The *only* reason I "flip the switch" is to test that it works. I never
    need it in real life.

    It's totally possible that the right solution is to remove the
    preference and force "expert" users to set the defaults in the terminal
    (hidden feature).

    But without understanding why people use it, I'll probably implement a
    bad solution, rather than a good one.

    Again -- thanks for your thoughts on this!

  11. 11 Posted by Stuart Hertzog on 21 Sep, 2017 03:13 AM

    Stuart Hertzog's Avatar

    I plead guilty to all charges, M'Lord!  But as you discovered, I'm not
    alone in doing this. As MMD is a superset of MD, for most people there's
    no need to change it, but it gets changed willy-nilly. As sole developer
    and support person, you want to reduce this user error, so you either
    use the command-line option, or create some kind of alert for the
    ignorant or forgetful.

    As I've been suggesting, I personally favour the latter: some kind of
    sign or alert that either shows the state of this preference, or warns
    people of the dire consequences should they attempt to change the
    Preference. Ideally, I'd like to see both, but of these two, I would
    give priority to an on-screen MD indicator (e.g. a little red box) that
    pops up a warning when hovered over.

    Hope that helps!

    Stuart

  12. Support Staff 12 Posted by Fletcher on 21 Sep, 2017 03:14 AM

    Fletcher's Avatar

    ;)

    Thanks!

    F-

  13. 13 Posted by lindsay on 21 Sep, 2017 03:06 PM

    lindsay's Avatar

    You asked the question 'Why does everyone keep turning on the Markdown compatibility mode and then act surprised when things that aren't Markdown don't work?'.

    As one of the other people who was head scratching when a table didn't render I guess the semantics of the checkbox label suggested (to me at least) that this widens the compatibility rather than narrows the features. Yes, I know that MMD > MD, but it wasn't obvious to me that this turned OFF full MMD support. If it was labelled something like 'Use Markdown format only' might have made it clearer.

  14. Support Staff 14 Posted by Fletcher on 21 Sep, 2017 03:43 PM

    Fletcher's Avatar

    Thanks for the feedback!

    F-

  15. 15 Posted by tuxtlequino on 21 Sep, 2017 04:14 PM

    tuxtlequino's Avatar

    I think it has to do with semantics. What is Markdown? I know it may be a pet peeve of yours since you developed MultiMarkDown, but I just call "MMD," "Markdown" all the time. I am guessing that is the case with a lot of people.

    May be make the option a lot clearer. Something like "Eliminate Multimarkdown features and do Markdown only."

  16. Support Staff 16 Posted by Fletcher on 21 Sep, 2017 04:29 PM

    Fletcher's Avatar


    So that I am not accused of trying to hijack Gruber's "brand" -- Markdown and MultiMarkdown are definitely two distinct things, though clearly related.

    Gruber created Markdown (both the syntax and the original Perl implementation). It was great, but (in opinion of many) needed more.

    MultiMarkdown is one (of many) supersets of the Markdown functionality. It can do everything Markdown does, and adds more (e.g. tables, footnotes, metadata, etc.)

    It is almost like being in the American South and knowing that "Pepsi" is a perfectly valid answer to the question, "What kind of Coke would you like?"

    Partially (IMO) because Markdown has not been touched in roughly 10 years, it has become more often used as a generic term for any of a group of loosely related implementations that process variations of the original syntax.

    That said, many people call MMD, Github-Flavored Markdown, commonmark, and many others "Markdown". I get it, but I feel compelled not to encourage it.

  17. 17 Posted by Stuart Hertzog on 21 Sep, 2017 05:37 PM

    Stuart Hertzog's Avatar

    This thread has been an interesting example of what I see as a broader issue in software engineering. Creative development very often is performed excellently by skilled programmers very immersed in their specialist domain, working in medium-size or small companies, or even one-person shops. But the majority of their users do not have the specialised knowledge of the developer; they view the finished product through a very different lens.

    Only the larger software companies can hire UI specialists and technical writers to translate the technical foundation into a GUI understandable by all levels of user. Even here, UI issues can arise, e.g. Apple's current WiFi toggle issue in iOS 11. As a former writer, editor, and occasional technical writer, my approach was always from the viewpoint of the non-savant. If I could not understand something without prior knowledge, it wasn't being explained properly.

    Right now, for lack of input from UI experts, a plethora of useful but specialised software lacks a user-friendly interface. MultiMarkdown Composer isn't one of these: credits to Fletcher for his skill. But as a relatively new Linux user, I'm running into this issue all the time. It's frustrating and consumes my time. I believe that it accounts for the limited uptake of Linux as a desktop OS. In a perfect world, every developer would have access to a UI expert before presenting the product to the public. In reality, issues such as this arise. Fortunately, they can be dealt with through forums such as this.

    The bottom line is that no matter how technical clever a software package may be, without an excellent UI its usefulness will be limited and its support requirements increased.

    Excuse the philosophical rambling. It's been an interesting thread!

  18. Support Staff 18 Posted by Fletcher on 21 Sep, 2017 06:23 PM

    Fletcher's Avatar

    Stuart,

    Good points.

    I appreciate your kind comment towards me, but I obviously fail at this
    sometimes too.

    A few random thoughts:

    1. The user interface is important to me. Microsoft Word generally
    works well enough, but the interface is horrible. It's not as bad as
    "back in the day" where it was not unusual to see something like 10 rows
    of buttons at the top of a window, with a small area for typing. Which
    means that overall I think it's a terrible application and never use it.

    2. The more that the interface can "disappear", the better. Composer 4
    (IMO) represents a big improvement over v2, which was an improvement
    over v1. If desired, the entire interface is literally a window with a
    box for typing. Or you can toggle on additional features if you need
    them (info bar, preview, etc).

    3. macOS does a reasonable job of funneling you towards better design
    instead of guiding you towards disaster. That helps.

    4. Windows had a history of cluttered interfaces -- lots of boxes and
    buttons all thrown together. I think that influenced the design of
    Linux GUI applications for many years. I think we have turned the
    corner on this, though I only use a handful of linux GUI applications,
    and the ones I use are more fairly classified as cross-platform (web
    browsers, Sublime Text, etc.)

    5. I see this starkly in my other role as a physician -- the interfaces
    for Electronic Medical Record software are terrible.... If the
    individuals making the purchasing decisions had to spend more time using
    them, I think we would be in a different situation.

    6. "Eating your own dog food" is necessary, but not sufficient. I do as
    much of my writing as possible in Composer, so I have to suffer the same
    issues as everyone else if I don't fix them. I still have to be mindful
    that I will still see the app in a different way than someone who is new
    to it.

    Again -- thanks for the input!

    F-

  19. Support Staff 19 Posted by Fletcher on 21 Sep, 2017 08:43 PM

    Fletcher's Avatar

    4.0.3 uses new terminology in the preferences. We'll see if the frequency of these reports decreases.

    Thanks!

  20. 20 Posted by Lindsay Davies on 22 Sep, 2017 08:59 AM

    Lindsay Davies's Avatar

    4.0.3 version now looks much clearer in its intent.

    L.

  21. Fletcher closed this discussion on 12 Oct, 2017 06:47 PM.

Comments are currently closed for this discussion. You can start a new one.

Keyboard shortcuts

Generic

? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac