Warnings/Recommendation system option


#1

###!tl;dr: Warning/Recommendations to help guard or clarify ambiguous inputs or bad practices. Presented via stderr or inline html, when a flag is set.

During authoring (like when you are typing up a post in discourse forum software), I think it is a good idea to implement a warning/recommendation system (much like what you see when compiling C.

The philosophy of markdown is that all inputs are valid inputs, so error system is out. However once we make CommonMark larger and more extendible (via generic directives), we really do need to implement a warning system to encourage good authorship.

Another use for this system, is dealing with ambiguous inputs. If there is an ambiguous input, the parser can pick the most likely option and throw a warning on it. This would give the author a chance to check if the parsed output is correct.

E.g.
!( example.com/image.png ) would throw a recommendation to define an alt text descriptor which is important for blind people.

This means users are encouraged to use ![]( example.com/image.png) to explicitly leave [] blank. Which would serve as a small reminder to define it. But at the same time, still allowing for lazy typing.


Presentation: This can be via typical warning logs ( via stderr ), but I would recommend that the warning be inline html like this <!> where you can click to expand the warning information. And only shown via a warning flag in the parser, that is recommended to be activated when the author is viewing/editing it, but not for the readers.


#2

I think some way to exclude particular warnings would be necessary. Some attributes might be added to the HTML after it is generated from the Markdown, such as height and width attributes pulled from the image file itself. If the intention is to show the warnings to the user, you probably don’t want to show all warnings at the end user level.


#3

I’d like the idea and think it might be implemented independently of extending the core language.

For example, by establishing an output convention that something that might have been intended as markup, but doesn’t meet the strict syntax requirements, is still treated as content but wrapped in an HTML <span> or <div>element with certain CommonMark specific class attribute(s) that allow a style-sheet to determine how to present it to the viewer. That way a default style-sheet might just display it, but one used in an editing view could highlight it.

I think this is really the tricky part of what you are proposing. I think you are talking about heuristics here. Could you illustrate with an example?

Wow, I’m not sure what tl;dr: means, but it might very well fit the definition of something that looks like markup but doesn’t fit the strict syntactic definition.


#4

too long, didn’t read


#5

I see, excellent. Gives me an idea on how one heuristic potentially worthy of warnings:

  • If the parser detects a whitespace-delimited word of content containing of more than one punctuation character, with or without other alphanumeric,
  • and the word does not match a list of white-listed regular expressions,
  • then it may flag this word using a span and the CSS class identifier ‘CommonMarkUnrecognized’

For example:

tl;dr: Warning/Recommendations to help...

might become:

<span class="CommonMarkUnrecognized">tl;dr:</span> Warning/Recommendations to help...

Which might alert authors to unfamiliar abbreviations in addition to it’s other uses. :slight_smile:


#6

Thank for clarifying tl;dr:

Under the CURIEs proposal (which might just deserve a TL;DR prefix) I suggest that might be written more clearly as <wp:TL;DR> or something, generating both short visual representation and a hyperlink. I invite your input.