Markdown or HTML ?

[patrickunterwegs]

re Markdown or not #323
Originally from https://gitlab.com/techbeeat1/jtx/-/issues/439 by @rogercreagh

I remain of the opinion that markdown should not be used in the plain description field as it is confusing to viewers who don't know markdown, and ugly to people who do know markdown.

Markdown lists work ok in plain text but it is mostly the bold, italic, and heading formats that are disturbing - plus more abstruse and complicated things like tables etc.

Less of an issue for Journals currently as there are few applications out there yet, but the same applies to ToDos and Memos/Notes.

I previously mentioned X-ALT-DESC as an alternative field but this is a bit specific to Microsoft (they use it for HTML in Outlook calendar entries), but I have subsequently discovered that RFC9073 updated RFC5545 to include a STYLED-DESCRIPTION property.

Extracts:

This property is used in the "VEVENT" and "VTODO" components to
capture lengthy textual descriptions associated with the activity.
This property is used in the "VJOURNAL" calendar component to
capture one or more textual journal entries.

...

VALUE=TEXT is used to provide rich text inline as the property
value.

...

In either case, the "DESCRIPTION" property should be absent or
contain a plain-text rendering of the styled text.

My feeling is that if markdown is to be included in the description then it should go in a separate STYLED-DESCRIPTION property and for backwards compatibility a plain text version (without markdown formatting) should be provided in DESCRIPTION.

This also opens the option of providing HTML in the STYLED-DESCRIPTION which may actually be more flexible as Markdown->HTML conversion is fairly simple (there are library functions for it) but the reverse is not true (HTML->Markdown).

Either way there is a property FMTTYPE which can be applied to STYLED-DESCRIPTION. Its default value if absent is text/html, but it could be set to text/markdown if it was desired to use styled description simply for markdown formatted text.

I don't think FMTTYPE is a recognised property for the DESCRIPTION in the rfc5545 spec.

In any event in the discussion below about sync'ing STYLED-DESCRIPTION the FMTTYPE should always be checked to determine what the remote system may have used - you might find a different system converts markdown in STYLED-DESCRIPTION to html.

So one way forward would be to allow Markdown when editing but immediately convert it to HTML and save it in STYLED-DESCRIPTION. Produce a plain text version from either the original markdown or the HTML (use strip_tags(); or equivalent in the source language) an put it in the DESCRIPTION.

An alternative would be to use FMTTTYPE=text/markdown for styled description, and save a markdown stripped version in the DESCRIPTION

When reading a sync'd entry if the date of the remote is newer than the local then there are there are a number of possibilities...

• It is a new entry with no local version to update and no styled-description

  • simply create a styled description from the new remote one

• it is a new entry with STYLED-DESCRIPTION present

  • in this case check the FMTTYPE property for the styled description and use it converting if necessary.

• it is an existing entry being updated by the remote and there is no styled-description present

  • the remote system must have stripped off the styled-description (which it should not do - it should ignore it)
  • it could be that the description is has not been updated but something else has, in which case we can use out existing styled-description. Test by making the same HTML-text conversion as when creating a new entry and compare the converted text with the remote one.
  • if they are the same then we are good to stick with out existing local styled description
  • If it has changed then out styled-description will need need updating so convert the remote text to html (it may contain Markdown so do it as a Markdown->html conversion which as a minimum will wrap it in <p>...</p> tags

• it is an existing entry with a styled description element present. In this case it is possible that the remote system has updated the description but ignored the styled-description. So we need to test if both remote elements match our local ones.

  • if DESCRIPTION has changed but STYLED-DESCRIPTION has not then the remote was not aware of the styled description and we need to update local description with the remote and create a new STYLED-DESCRIPTION version from the new text
  • if styled description has changed but plain description has not then the remote has (wrongly) assumed it can ignore the plain text version. So update our local styled description with the remote and replace the local description with one created from the new styled version
  • if both have changed then we can simply update both. For viewing we will be using the styled description and if we edit we will update the plain text with our own conversion from the styled version (which may not be the same as the way the remote system does it, but hey ho!)

Sorry for the long post, but I hope the discussion is useful.I do think continuing with putting formatted text of any type (including markdown) in the DESCRIPTION is dangerous and not in line with the spec.

[rogercreagh]

I still think markdown is a styled-description not plain text, but it may be complex to implement and the lack of discussion on this probably means that those who use markdown don't share their work with those who don't understand it so everyone is happy to simply use the description field as they see fit.

[tusch001]

I write here not as a programmer - I don't know much about that.
Sorry, long text - feel free to ignore, it's just an opinion.

What I want to mention here is some everyday work experience in a small office and what happens if you allow any html in text fields:

When we transitioned some years ago from sending our customers pdf files with product information to let them view everything on the web I encountered strange formatting on my webpage displaying text. The information on the webpage was entered by my colleagues in fields with editors that converted the field to html but allowed the user to format bold / italic / ...

Sometimes the input on the webpage just looked weired.

Why? Because people are people and are lazy:

Sometimes they copied and pasted the text from their text processing software on the desktop directly into the text fields while editing the web page. Some users didn't know the difference between copying plain text and html formatted text. And you would not believe how much formatting was in the text done by the desktop software. Which was allowed by the editor because they were considered "harmless" tags, e.g. <i>, <span>, <p>. Even if the text looked as plain text during input different desktop applications added lots of other attributes to these tags (such as style="font: ... ; text-align: .."). Or added tags as <style>, <font>, <color>.

After having too many discussions about how to correctly copy & paste text (without html as plain text) I changed the field type on my webpage from formatted html text to markdown with a markdown editor that allowed only few html tags and attributes.

I write this because I think you will encounter the same problem in the long run. You will have to take care of all the possible html formatting that might be allowed / forbidden in any pasted text. Or sooner or later this will be visible on the display (e.g. if there is a future nextcloud desktop app for displaying these calendar notes).

I see the future of jtx board in a "replacement" of evernote (without the attachment of big files which can be linked). But the more people are using it the more you will have to deal with people who don't understand what the are doing.

Sorry for the long input.

BTW: thanks for jtx board

[rogercreagh]

Useful input @tusch001 .
I agree html input should only be used in special circumstances where there is good control over the input. Letting general users loose with a complete HTML toolbar is a recipe for a mess, and pasting as html from word (etc) has always been a disaster when you look at the bloated code full of extra spurious (outside word) tags.

For jtxB I don't see any need or possibility of providing html editing - its simply not appropriate on a mobile device. The vJournal spec requires a plain text description to be available, any other formats are extra and do not have to be displayed. There are problems keeping the content in sync with other formats (and even with plain text if multiple language versions are in play)

My beef is the use of markdown in the plain text description without flagging it. If another app doesn't know markdown has been used it will display all the markdown codes as text, which for me is a ###mess for the user, especially if he doesn't know what markdown is.

The fallback is to always display the description as markdown - if there are no markdown codes present it will still display ok. This is the approach I am forced to take in my app, but I'm not convinced that all other apps (Evolution, KDE and various task apps) do this. (of course providing a parameter that said this description contains markdown wouldn't help any existing apps without them implementing it)