search

riboseinc / ribose-api

API for Ribose
0 stars 0 forks source link

Unrecognized comment block validation error #36

Closed skalee closed 6 years ago

skalee commented 6 years ago

Validator says:

warning code 5 in line 195 - ignorning unrecognized block:
    [comment]: <> (REFERENCE section)
skalee commented 6 years ago

These comment blocks may have something to do with Hercule.

ribose-jeffreylau commented 6 years ago

I think these are meant to be actual comments.

Are there any better alternatives for commenting?

skalee commented 6 years ago

Looks like this is an attempt to insert HTML comment: https://stackoverflow.com/a/20885980/304175

skalee commented 6 years ago

I've tried all reasonable ways of comment insertion in Markdown I could find in StackOverflow:

[comment]: <> (This is a comment, it will not be included)
[//]: <> (This is also a comment.)
[//]: # (This may be the most platform independent comment)
<!-- HTML comment -->

Neither passed our blueprints validator. Also, according to https://github.com/apiaryio/api-blueprint/issues/139, they aren't supported purposely for aesthetic reasons, despite numerous community requests.

I see three options:

  1. Remove comments altogether, they're only present in input.apib, and IMHO we can live without them.
  2. Enhance validator so that it ignores this particular warning.
  3. Implement some pre- or post processing (e.g. sed, awk, grep) which removes comments. We use make anyway. (On the other hand, I'm not sure whether we should sick to *nix-specific make in a long term.) Also templating engines could do the trick, they typically support comments which are removed on render.
  4. Discuss comments support in Hercule issue tracker. Anyway, they're most useful when merging subdocuments.

I think we should go either with 1) – no comments = no problems, or 3) which is pretty simple to implement, it's just a simple regular expression to be passed to sed/awk/grep.

skalee commented 6 years ago

Just found a nice NPM package: https://www.npmjs.com/package/erase. It erases marked parts from document. However, there will be blank lines leftovers, so perhaps sed is better.

skalee commented 6 years ago

This might be also doable with Hercule's resolvers, if we define a custom "comment" resolver which always returns some empty content. I'm pretty sure it's the best option for now, and I'll do some experimenting.

skalee commented 6 years ago

Follow-up after experimenting – we got 3 options:

  1. Remove comments
  2. Use sed/awk/grep (or some JavaScript one-liner which removes comments with regular expressions)
  3. Implement Hercule's resolver

First two are described in earlier comments. The third one is easy to do, however has two flaws.

Firstly, it must fit transclusion syntax (:[]()). It will look like quite weird, especially that whatever is between parentheses, must be an URI.

:[This is a comment](comment)
:[This is a comment](//)
:[](comment:This-is-also-a-comment-but-whitespaces-ale-disallowed-here)

Secondly, there is no way to remove leading and trailing blank lines, hence resulting apiary.apib may contain several subsequent newlines which are meaningful in Markdown. On the other hand, we got few already and this doesn't seem to be a problem.

So, what we do? And if resolver, which syntax? Personally I'm slightly against resolvers because of syntax requirements which make things look weird.

ribose-jeffreylau commented 6 years ago

Agreed. 1. and 2. seem to be the best options for now.

2 seems the most flexible, and it's easy to modify.