The curious tale of underscores (parsing preference error, usability bug or spec oversight)

[Almad]

Imagine a need to describe a parameter like this one:

+ underscore_param: `default_underscorevalue` (string) - This is parameter that uses underscore_values

that can be in either payload or URL parameter.

Unfortunately, Markdown's preference to treat text between underscore as italic probably takes preference over standard parsing rules, messing the resulting AST.

I think this is a bug that should be fixed.

(Missing) Workarounds

When using as MSON in Attributes section, the workaround is to put underscore_param into backticks:

+ Attributes
    + `underscore_param`: `default_underscorevalue` (string) - This is parameter that uses underscore_values

This produces expected result.

Unfortunately, in Parameters section, enclosing parameter name into backticks causes the parameter line to be ignored. Therefore, to my knowledge, there is currently no way to describe a parameter that contains _ in both parameter name and default value.

[pksunkara]

Markdown's preference to treat text between underscore as italic probably takes preference over standard parsing rules, messing the resulting AST.

Actually, underscore is a reserved character in MSON.

I think this is a bug that should be fixed.

It's not a bug. We can improve the UI around this though by using some kind of warning.

Unfortunately, in Parameters section, enclosing parameter name into backticks causes the parameter line to be ignored

This is being tracked in #123

[pksunkara]

The UX improvement is being tracked in https://github.com/apiaryio/api-blueprint/issues/210

[Almad]

Actually, underscore is a reserved character in MSON.

But it is behaving differently than other reserved characters like dash; if I add dash, the whole line is not valid at all—while underscore is invalid only in specific circumstances.