The Description Problem

[stairman06]

How do you store a mod description? This goes through some options and lists their pros and cons.

Markdown

Pros:

• Easy to read, easy to write
• Nearly universal
• Will require no extra compilation in most cases, as mod authors likely already use Markdown

Cons:

• Multiple flavors
  • We would have to decide on one to use. GFM seems like a good choice.
• Lacks support for other elements which might be useful, like YouTube embeds or spoilers

Pure HTML

Pros:

• Every system has an HTML parser
• Works with nearly all markup languages which compile to HTML

Cons:

• Security problems with XSS
  • Requires lots of filtering and sanitization
• Markdown must be compiled to this before used

Custom HTML subset-like format (e.g. Formatted Text)

Pros:

• HTML can be transformed to the custom format easily
• XML parsers are very common
• Allows full control and custom elements (like YouTube embeds)

Cons:

• Markdown must be compiled to this before used
• More effort to maintain

Ruled-out ideas

Other ideas have been suggested, but I think these should be ruled out due to various flaws.

Allowing any format

This would allow any format to be used, as long as it's specified correctly. The problem with this is the implementation. Any implementation would have to implement multiple language readers, which is complicated and leads to confusion.

Another markup format (e.g. Asciidoc)

Other markup formats have too little usage in order to be justifiable. Transforming Markdown to another format, like Asciidoc, requires effort and may not lead to good quality in some cases. Instead, it might be better to use HTML or a subset, which nearly every markup language can already compile to.

All feedback. opinions, and discussion are welcome.

[immibis]

For me, markdown is right out because:

• It's not consistent - it has different variations
• It's too opinionated - how do you put bold text inside a code block? You don't.
• The second point makes it very difficult to convert other formats to Markdown, because the text in the other format might not conform to Markdown's opinion and then you can't convert it. (you can write bold code in HTML, how do you convert it to Markdown? Remove the boldness?
• Although it may be nearly universal, it's not universal, and each variant especially isn't universal. Each variant should actually be treated as a different language.

Asciidoc has the exact same problems as Markdown. It may as well be a variant of Markdown for this discussion.

And multi-format is also right out. Multi-format forces every client to include a parser for every format, which is just stupid. Even mandating HTML would be better than that idea. (if they have to include an HTML parser anyway, why not make it the only parser?)

[stairman06]

I am leaning towards an HTML subset personally. It would cover nearly every use-case and doesn't have the problems of Markdown and any of its variants.