Formatting the data

[KamasamaK]

See PR 880 comment and PR 877 comment thread for background.

I agree that HTML should be avoided. I am curious if anyone thinks more markdown should be supported or if we should avoid more formatting. Regardless, it should be documented what's supported.

I've also found that there are too many new lines in places they are not needed, such as in the middle of a sentence. I can understand in some cases wanting to start a new line, but I do not think, for instance, that we should be enforcing some kind of line length in the data.

Please provide your opinions on this.

[pfreitag]

My thoughts on this are:

• I don't want HTML in the json
• I think a subset of markdown might make sense (eg backticks are already supported), but I don't think full blown markdown is necessary. My question would be what formatting options of markdown do we need and why? My concern with a full markdown implementation is that the docs might be harder for third parties to use (eg IDE's), it's not really a technical one since we already support markdown for the guides.
• I agree that the newlines should be removed, I have been removing them when I edit a doc that has them.

[shaedrich]

We should have an overview of which formatting is supported for which values.

[shawnoden]

Did we ever build out this formatting overview? A lot of what I've been doing is trying to correct formatting on the tags when I come across them, but I didn't really see any consistent documentation of preferred formatting.

[shaedrich]

I don't think so. But feel free to start that.

[pfreitag]

We'll let's start with my question from a few comments ago: My question would be what formatting options of markdown do we need and why?

As noted above backticks are currently supported, but if you get too complicated with markdown support then different markdown engines have slightly different results (eg: some support tables some do not).

If we can get away with a subset of full blown markdown support I think that would be best. Especially for those supporting the descriptions in IDE's or other projects it complicates their requirements (you don't need a markdown library to replace back ticks with <code> tags but you may need a library for more complicated markdown features).

[shawnoden]

I'd be glad to put something more formal together. Do we have any basic guidelines? Which fields is Markdown applicable to? Is there anything other than the backticks usable in description? What is the proper way to write out a new line (\n\r, \r\n, just one of those, or something else)? How should we format a description that includes a list (like datepart param of dateAdd)? Do we have anything that details what the parts of the JSON are for, or the parts that should or could be included? And probably a bazillion other questions.

As someone who has used this resource for a long time, my two main concerns are: 1) That this site looks good to a user. This includes consistency. 2) That changes don't break or affect IDEs or anything else that uses CFDocs.

And as someone who has found myself motivated to contribute: 1) I want to know how to properly contribute and share that knowledge with anyone else wanting to also contribute. 2) I don't want to re-tread ground that's already been covered. 2a) I don't want my submissions to be incorrect because I did something wrong without realizing I was wrong (like trying to use HTML in descriptions). 2b) I don't want to waste anyone's time by doing 2.

[shaedrich]

@pfreitag I guess, it's not about changing that, it's about documenting where which formatting is supported so contributors know what can be formatted in which way.

[shawnoden]

@pfreitag I can't speak for anyone else, but in my changes, the things that I've come across that I would like to have (beyond backticks) would be bold, italics and unordered lists. I'm not sure that full blown Markdown is needed for those, but like I said above, I wouldn't want to break IDEs by having things like that.

[pfreitag]

@shaedrich gotcha -- so I think the only places that have extended formatting are the description fields and the notes field in the engines.

Right now that extended formatting happens in the autoLink function: https://github.com/foundeo/cfdocs/blob/master/Application.cfc#L58 which originally just turned URL's into links but was modified to also add:

• convert backticks to code tags
• replace patterns like CF6+ or Lucee5+ with a label or
• replace \n with <br>

[pfreitag]

@shawnoden - yeah I think those three things make sense, and could be done in such a way that it wouldn't break the view of an editor that didn't support them. So I'm ok with those changes if anyone wants to submit a PR to modify autoLink to do that -- I would say you should also refactor the name autoLink and change it to something like formatText or something.

[shawnoden]

@pfreitag Does it also replace \r with <br>, or is that getting interpreted as another line feed character? I've come across places where \r\n or \n\r will function like a CRLF and only one line will get inserted, but others both seem to be interpreted and two lines are inserted.

[pfreitag]

no it just replaces the \n - I'd rather use \n than \r\n it is unnecessary to use the carriage return \r in the json, so I would prefer not to see \r in the json.

[pfreitag]

The \r\n is a valid CRLF but \n\r is not valid -- it is LFCR.

Unix just uses \n LF but windows uses CRLF

[shawnoden]

Works for me. I ask because I came across \n\r, \n and \r in some of these functions. Which was one of the reasons I was trying to fix some of the consistency.

And the \n\r seemed weird to me too, but the JSON formatting utility does it that way. I used it to fix some JSON I couldn't get to validate and it inserted those on my new lines.

[shawnoden]

Awesome. And that looks like it's a serializeJSON() thing. And a Lucee serializeJSON() thing to boot. ACF appears to only output a \n. So, does that qualify as a Lucee bug for anyone else? It's non-breaking, but it does seem semantically incorrect, and it disagrees with ACF's implementation.

[pfreitag]

Yeah - I would report that as a bug on Lucee

[jmharrin]

I created a pull request to update txtmark to flexmark (Java library for parsing and rendering Markdown text according to the CommonMark specification). I included the extension to also support table formatting using pipe "|" syntax rules. #1361